Setup and Config
Getting and Creating Projects
Basic Snapshotting
Branching and Merging
Sharing and Updating Projects
Inspection and Comparison
Patching
Debugging
External Systems
Server Admin
Guides
- gitattributes
- Command-line interface conventions
- Everyday Git
- Frequently Asked Questions (FAQ)
- Glossary
- Hooks
- gitignore
- gitmodules
- Revisions
- Submodules
- Tutorial
- Workflows
- All guides...
Administration
Plumbing Commands
- 2.48.1 → 2.49.0 no changes
-
2.48.0
2025-01-10
- 2.46.1 → 2.47.2 no changes
-
2.46.0
2024-07-29
-
2.45.3
2024-11-26
- 2.45.1 → 2.45.2 no changes
-
2.45.0
2024-04-29
- 2.44.1 → 2.44.3 no changes
-
2.44.0
2024-02-23
- 2.43.2 → 2.43.6 no changes
-
2.43.1
2024-02-09
-
2.43.0
2023-11-20
- 2.42.2 → 2.42.4 no changes
-
2.42.1
2023-11-02
-
2.42.0
2023-08-21
- 2.41.1 → 2.41.3 no changes
-
2.41.0
2023-06-01
- 2.40.1 → 2.40.4 no changes
-
2.40.0
2023-03-12
- 2.38.1 → 2.39.5 no changes
-
2.38.0
2022-10-02
- 2.36.1 → 2.37.7 no changes
-
2.36.0
2022-04-18
- 2.35.1 → 2.35.8 no changes
-
2.35.0
2022-01-24
- 2.34.1 → 2.34.8 no changes
-
2.34.0
2021-11-15
- 2.33.1 → 2.33.8 no changes
-
2.33.0
2021-08-16
- 2.32.1 → 2.32.7 no changes
-
2.32.0
2021-06-06
- 2.31.1 → 2.31.8 no changes
-
2.31.0
2021-03-15
- 2.30.1 → 2.30.9 no changes
-
2.30.0
2020-12-27
- 2.29.1 → 2.29.3 no changes
-
2.29.0
2020-10-19
- 2.28.1 no changes
-
2.28.0
2020-07-27
- 2.27.1 no changes
-
2.27.0
2020-06-01
- 2.25.2 → 2.26.3 no changes
-
2.25.1
2020-02-17
-
2.25.0
2020-01-13
- 2.24.1 → 2.24.4 no changes
-
2.24.0
2019-11-04
- 2.23.1 → 2.23.4 no changes
-
2.23.0
2019-08-16
- 2.22.1 → 2.22.5 no changes
-
2.22.0
2019-06-07
- 2.21.1 → 2.21.4 no changes
-
2.21.0
2019-02-24
- 2.20.1 → 2.20.5 no changes
-
2.20.0
2018-12-09
- 2.19.1 → 2.19.6 no changes
-
2.19.0
2018-09-10
- 2.18.1 → 2.18.5 no changes
-
2.18.0
2018-06-21
- 2.17.1 → 2.17.6 no changes
-
2.17.0
2018-04-02
-
2.16.6
2019-12-06
-
2.15.4
2019-12-06
-
2.14.6
2019-12-06
-
2.13.7
2018-05-22
-
2.12.5
2017-09-22
-
2.11.4
2017-09-22
- 2.10.5 no changes
-
2.9.5
2017-07-30
-
2.8.6
2017-07-30
-
2.7.6
2017-07-30
-
2.6.7
2017-05-05
-
2.5.6
2017-05-05
-
2.4.12
2017-05-05
- 2.2.3 → 2.3.10 no changes
-
2.1.4
2014-12-17
-
2.0.5
2014-12-17
RESUMO
git format-patch [-k] [(-o|--output-directory) <dir> | --stdout] [--no-thread | --thread[=<style>]] [(--attach|--inline)[=<boundary>] | --no-attach] [-s | --signoff] [--signature=<signature> | --no-signature] [--signature-file=<file>] [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] [--in-reply-to=<message-id>] [--suffix=.<sfx>] [--ignore-if-in-upstream] [--always] [--cover-from-description=<mode>] [--rfc[=<rfc>]] [--subject-prefix=<subject-prefix>] [(--reroll-count|-v) <n>] [--to=<email>] [--cc=<email>] [--[no-]cover-letter] [--quiet] [--[no-]encode-email-headers] [--no-notes | --notes[=<ref>]] [--interdiff=<previous>] [--range-diff=<previous> [--creation-factor=<percent>]] [--filename-max-length=<n>] [--progress] [<common-diff-options>] [ <since> | <revision-range> ]
DESCRIÇÃO
Prepare cada commit não mesclado com seu "patch" numa "mensagem" por commit, formatada para se assemelhar a uma caixa de correio do UNIX. A saída desse comando é conveniente para envio por e-mail ou para uso em conjunto com o comando git am.
Uma "mensagem" gerada pelo comando consiste em três partes:
-
Um breve cabeçalho de metadados que começa com
From <commit>
com um registro de data e hora fixo, comoSeg Set 17 00:00:00 2001
para auxiliar programas como "arquivo(1)" a reconhecer que o arquivo foi gerado deste comando, campos que registrem a identidade do autor, a data da autoria e o título da alteração (retirado do primeiro parágrafo da mensagem do log do commit). -
O segundo ou o parágrafo subsequente da mensagem do registro do commit.
-
O "patch", que é gerado com o comando "diff -p --stat" (consulte git-diff[1]) entre o commit e a fonte principal.
A mensagem de registro e o patch são separados por uma linha com três traços.
Existem duas maneiras de especificar em quais commits operar.
-
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. -
A expressão genérica <faixa-da-revisão> (consulte a seção "ESPECIFICANDO REVISÕES" do comando gitrevisions[7]) significa os commits no intervalo especificado.
A primeira regra tem precedência no caso de um único <commit>. Para aplicar a segunda regra, ou seja, formatar tudo desde o início do histórico até <commit>, use a opção --root
: git format-patch --root <commit>
. Se quiser formatar apenas o <commit>, você pode fazer isso com git format-patch -1 <commit>
.
É predefinido que cada arquivo gerado seja numerado de maneira sequencial a partir de 1 e usa a primeira linha da mensagem de confirmação (ajustada para segurança do nome do caminho) como o nome do arquivo. Com a opção --numbered-files
, os nomes dos arquivos de saída serão apenas números, sem a primeira linha do commit anexada. Os nomes dos arquivos gerados são impressos na saída predefinida, a menos que a opção --stdout
seja especificada.
Caso a opção -o
seja usada, os arquivos gerados serão criados em <dir>. Caso contrário, eles sã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 format.outputDirectory
. Para armazenar as correções no diretório de trabalho atual, mesmo quando o format.outputDirectory
apontar para outro local, use -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árias correções forem emitidas, o prefixo do assunto será "[PATCH n/m] ". Para forçar a adição de 1/1 numa única correção, use -n
. Para omitir números dos patches de correção do assunto, use a opção -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 das correções (patches) subsequentes apareçam como resposta ao primeiro e-mail; isso também gera um cabeçalho Message-Id
para a referência.
OPÇÕES
Warning
|
Missing See original version for this content. |
- -<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 um trailer
Signed-off-by
à mensagem do commit, usando a sua identidade de committer. Consulte a opção signoff do comando git-commit[1] para obter mais informações. - --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
eReferences
para fazer com que o segundo e-mail e os seguintes apareçam como respostas ao primeiro. Também controla a geração do cabeçalhoMessage-ID
para referência.O argumento opcional <estilo> pode ser
shallow
oudeep
. A instância shallow faz com que cada e-mail seja uma resposta ao cabeçalho da série, onde o cabeçalho é escolhido a partir da carta de apresentação do--in-reply-to
e do primeiro e-mail de correção, nesta ordem. A instância deep faz com que cada e-mail seja uma resposta a resposta anterior.A predefinição é
--no-thread
, a menos que a configuraçãoformat.thread
seja definida. A opção--thread
sem um argumento é o mesmo que--thread=shallow
.Observe que o padrão do git send-email é cadenciar os próprios e-mails. Se você quiser que o
git format-patch
cuide do encadeamento, será necessário garantir que o encadeamento esteja desativado para ogit send-email
. - --in-reply-to=<id-da-menssagem>
-
Faz com que o primeiro e-mail (ou todos os e-mails que estejam usando
--no-thread
) apareça como uma resposta ao <id-da-menssagem> informado, o que evita a quebra das threads para fornecer uma nova série de correções. - --ignore-if-in-upstream
-
Não inclua uma correção que corresponda a um commit em
<até>..<desde>
. Isso examinará todas as correções acessíveis a partir de <desde>, mas não de <até> e os comparará com as correções que estão sendo geradas, e qualquer correção correspondente será ignorado. - --always
-
Inclua as correções para os commits que não apresentam nenhuma alteração, que por predefinição, são omitidos.
- --cover-from-description=<mode>
-
Controla quais as partes da carta de apresentação serão preenchidas automaticamente utilizando ao descritivo do ramo.
Caso
<modo>
sejamessage
oudefault
, 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>
sejasubject
, 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>
sejaauto
e se o primeiro parágrafo do descritivo do ramo for maior que 100 bytes, o modo serámessage
, caso contrário, osubject
será utilizado.Caso
<modo>
sejanone
, tanto o assunto e o corpo da carta serão preenchidos com o texto do espaço reservado. - --description-file=<arquivo>
-
Use o conteúdo do <arquivo> em vez da descrição do ramo para gerar a carta de apresentação.
- --subject-prefix=<prefixo-do-assunto>
-
Em vez do prefixo padrão [PATCH] na linha de assunto, use [<prefixo-do-assunto>]. Isso pode ser usado para nomear uma série de correções e pode ser combinado com a opção
--numbered
.A variável de configuração
format.subjectPrefix
também pode ser usada para configurar um prefixo de assunto que será aplicado a um determinado repositório para todos os patches. Isso costuma ser útil em listas de discussão que recebem patches de vários repositórios e pode ser usado para desambiguar os patches (com um valor de, por exemplo, "PATCH my-project"). - --filename-max-length=<n>
-
Em vez dos 64 bytes predefinidos, corte os nomes de arquivos gerados na saída em cerca de <n> bytes (um valor muito curto será silenciosamente aumentado para um tamanho razoável). A predefinição é o valor na variável de configuração
format.filenameMaxLength
ou 64, caso não esteja configurada. - --rfc[=<rfc>]
-
Prepends the string <rfc> (defaults to "RFC") to the subject prefix. As the subject prefix defaults to "PATCH", you’ll get "RFC PATCH" by default.
RFC means "Request For Comments"; use this when sending an experimental patch for discussion rather than application. "--rfc=WIP" may also be a useful way to indicate that a patch is not complete yet ("WIP" stands for "Work In Progress").
If the convention of the receiving community for a particular extra string is to have it after the subject prefix, the string <rfc> can be prefixed with a dash ("
-
") to signal that the rest of the <rfc> string should be appended to the subject prefix instead, e.g.,--rfc='-(WIP)'
results in "PATCH (WIP)". - -v <n>
- --reroll-count=<n>
-
Marque a série como a <n>-ésima iteração do tópico. Os nomes dos arquivos de saída têm
v<n>
anexado a eles, e o prefixo do assunto ("PATCH" por padrão, mas configurável através da opção--subject-prefix
) tem ` v<n>` anexado a ele. Por exemplo,--reroll-count=4
pode produzir o arquivov4-0001-add-makefile.patch
que tem "Subject: [PATCH v4 1/20] Add makefile" nele. O<n>
não precisa ser um número inteiro ("--reroll-count=4.4" ou "--reroll-count=4rev2" são permitidos por exemplo), mas a desvantagem de usar esse tipo de reroll-count é que o range-diff/interdiff com a versão anterior não indica exatamente com qual versão a nova iteração é comparada. - --to=<e-mail>
-
Adicione um cabeçalho
To:
aos cabeçalhos de e-mail. Isso se soma a qualquer cabeçalho configurado e pode ser usado várias vezes. A forma negada--no-to
descarta todos os cabeçalhosTo:
adicionados até o momento (a partir da configuração ou da linha de comando). - --cc=<e-mail>
-
Adicione um cabeçalho
Cc:
aos cabeçalhos de e-mail. Isso se soma a qualquer cabeçalho configurado e pode ser usado várias vezes. A forma negada--no-cc
descarta todos os cabeçalhosCc:
adicionados até o momento (a partir da configuração ou da linha de comando). - --from
- --from=<ident>
-
Utilize
ident
(identidade) no cabeçalhoDe:
de cada email do commit. Caso oident
do autor do commit não seja textualmente idêntica aoident
informado, coloque um cabeçalhoDe:
no corpo da mensagem com o autor original. Caso nenhumident
seja informado, utilize oident
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 comandogit 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 comandogit send-email
. - --[no-]force-in-body-from
-
Com o remetente do e-mail especificado por meio da opção
--from
, é predefinido que, um "From:" no corpo da mensagem para identificar o verdadeiro autor do commit é adicionado na parte superior da mensagem de registro do commit se o remetente for diferente do autor. Com essa opção, o "From:" no corpo da mensagem é adicionado mesmo quando o remetente e o autor têm o mesmo nome e endereço, o que pode ajudar se o software da lista de discussão confundir a identidade do remetente. A predefinição é o valor na variável de configuraçãoformat.forceInBodyFrom
. - --add-header=<cabeçalho>
-
Adiciona um cabeçalho arbitrário aos cabeçalhos do e-mail. Isso se soma a qualquer cabeçalho configurado e pode ser usado várias vezes. Por exemplo,
--add-header="Organization: git-foo"
. A forma negada--no-add-header
descarta todos os cabeçalhos (To:
,Cc:
e os personalizados) adicionados a partir da configuração ou da linha de comando. - --[no-]cover-letter
-
Além das correções, gere um arquivo tipo carta de apresentação contendo a descrição da ramificação, o registro curto 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 auxílio ao revisor, insira um "range-diff" (consulte git-range-diff[1]) na carta de apresentação ou como comentário da única correção de uma série de 1 correções, mostrando as diferenças entre a versão anterior da série de correções e a série que está sendo formatada no momento.
previous
pode ser uma única revisão nomeando a ponta da série anterior se ela compartilhar uma base comum com a série que está sendo formatada (git format-patch --cover-letter --range-diff=feature/v1 -3 feature/v2
por exemplo), ou uma faixa de revisão se ambas versões da série forem distintas (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 dorange-diff
usado para gerar o material da carta de apresentação (isso pode mudar no futuro). - --creation-factor=<percentual>
-
Usado com
--range-diff
, ajusta a heurística que combina os commits entre a série anterior e a atual de patches, ajustando o fator de correção do custo de criação/exclusão. Para mais detalhes consulte git-range-diff[1]).Defaults to 999 (the git-range-diff[1] uses 60), as the use case is to show comparison with an older iteration of the same topic and the tool should find more correspondence between the two sets of patches.
- --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 donotes.rewrite
em git-notes[1] para compreender este fluxo de trabalho).A predefinição é
--no-notes
, a menos que a configuraçãoformat.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 num arquivo. - --suffix=.<sfx>
-
Em vez de usar
.patch
como sufixo para os nomes de arquivos gerados, use o sufixo especificado. Uma alternativa comum é--suffix=.txt
. Deixar esse campo vazio removerá o sufixo.patch
.Observe que o caractere principal não precisa ser um ponto; você pode usar
--suffix=-patch
para obter0001-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 exiba o conteúdo das alterações em arquivos binários; em vez disso, exiba um aviso de que esses arquivos foram alterados. As correções geradas com essa opção não podem ser aplicadas corretamente, mas ainda são úteis para a revisão de 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 árvore base para identificar o estado ao qual a série de correções se aplica. Para mais detalhes consulte a seção INFORMAÇÕES SOBRE A ÁRVORE BASE abaixo. Se o <commit> for "auto", um commit básico será escolhido automaticamente. A opção
--no-base
substitui uma configuraçãoformat.useAutoBase
. - --root
-
Trate o argumento de revisão como um <intervalo-da-revisão>, mesmo que seja apenas um único commit (que normalmente seria tratado como um <desde>). Observe que os commits raiz incluídos no intervalo especificado são sempre formatados como correções de criação, independentemente desta opção.
- --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 será colocado na pasta de rascunhos do MUA, editado para adicionar comentários oportunos que não devem ir para o changelog após os três traços e, em seguida, enviado como uma mensagem cujo corpo, em nosso exemplo, começa com "arch/arm config files were…". Na extremidade receptora, os leitores podem salvar correções interessantes numa caixa de correio UNIX e aplicá-las com git-am[1].
Quando uma correção faz parte de uma discussão em andamento, a correção gerada pelo git format-patch pode ser ajustada para aproveitar o recurso git am --scissors. Após a sua resposta à discussão, vem uma linha que consiste apenas em "-- >8 --
" (tesoura e perfuração), seguida da correção com os campos de cabeçalho desnecessários removidos:
... > Então faremos assim e assado. Faz sentido para mim. Que tal este patch? -> 8 - Assunto: [IA64] Coloque os arquivos da configuração do ia64 na dieta Uwe Kleine-König Os arquivos da configuração arch/arm foram reduzidos utilizando um script python ...
Ao enviar uma correção dessa forma, na maioria das vezes você está enviando a sua própria correção, portanto, além do marcador "From $SHA1 $magic_timestamp
", você deve omitir as linhas From:
e Date:
do arquivo de correção. É provável que o título do patch seja diferente do assunto da discussão à qual a correção está respondendo, portanto, é provável que você queira manter a linha Subject:, como no exemplo acima.
Verificando o corrompimento dos patches
Muitos remetentes, se não forem configurados corretamente, corromperão os espaços em branco. Aqui estão dois tipos comuns de corrupção:
-
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 essa correção num arquivo no formato de caixa de correio do UNIX. Chame-o de a.patch, por exemplo.
-
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.
-
A correção em si não é aplicada de forma limpa. Isso é ruim, mas não tem muito a ver com seu MUA. Talvez, neste caso, você queira fazer o rebase da correção com git-rebase[1] antes de regenerá-la.
-
O MUA corrompeu a sua correção; o "am" reclamaria que a correção não se aplica. Dê uma olhada no subdiretório .git/rebase-apply/ e veja o que o arquivo de correção patch contém e verifique se há os padrões comuns de corrupção mencionados acima.
-
Enquanto isso, verifique também os arquivos info e final-commit. Se o que estiver em final-commit não for exatamente o que você gostaria de ver na mensagem de registro do commit, é muito provável que o receptor acabe editando manualmente a mensagem de registro ao aplicar a correção. Coisas como "Oi, esta é a minha primeira correção.\n" no e-mail de correção devem vir depois da linha de três traços que sinaliza o fim da mensagem de confirmação.
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 nenhuma maneira de desativar a quebra de linha na interface da Web, portanto, ele vai distorcer todos os e-mails que você enviar. No entanto, você pode usar o "git send-email" e enviar suas correções por meio do servidor SMTP do GMail ou usar qualquer cliente de e-mail IMAP para se conectar ao servidor IMAP do Google e encaminhar os e-mails por meio dele.
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-imap-send[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:
-
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)".
-
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: Editar…Preferências…Avançado…Editor de configuração. Busque por "mail.wrap_long_lines". Altere e tenha certeza que esteja definido como
false
. Além disso, procure por "mailnews.wraplength" e defina o valor como 0. -
Desative o uso de
format=flowed
: Editar…Preferências…Avançado…Editor de configuração. Busque por "mailnews.send_plaintext_flowed". Altere e tenha certeza que esteja definido comofalse
.
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)
São necessárias as seguintes extensões do Thunderbird: AboutConfig de https://mjg.github.io/AboutConfig/ e External Editor de https://globs.org/articles.php?lng=en&pg=8
-
Prepare o patch como um arquivo de texto utilizando o seu método preferido.
-
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.
-
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
-
Abra uma janela de composição e clique no ícone do editor externo.
-
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.
-
Prepare o patch como um arquivo de texto.
-
Clique em "New Mail".
-
Vá em "Opções" na janela do Compositor verifique se "Quebra de linha" não está definido.
-
Utilize Mensagem → Inserir arquivo → e insira o patch.
-
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.
O "commit básico" é mostrado como "base-commit: " seguido do 40 hexadecimal do nome do objeto do commit. Uma "pré-requisito de correção" é mostrado como "prerequisite-patch-id: " seguido do "patch id" de 40 hexadecimais, que pode ser obtido passando a correção 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.
Se for definido --base=auto
na linha de comando, ele calculará automaticamente o commit base como a base de mesclagem do commit do cume do ramo rastreado remotamente e do intervalo de revisão especificado na linha de comando. Para uma ramificação local, você precisa fazer com que ela faça o rastreios de uma ramificação remota com git branch --set-upstream-to
antes de usar essa opção.
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 lida com renomeações e reescritas completas de forma inteligente para produzir uma correção de renomeação. Uma renomeação de uma correção reduz a quantidade de saída de texto e, em geral, facilita a revisão. Observe que os programas de "correção" que não são do Git não entenderão a renomeação de correções, portanto, use-a somente quando souber que o destinatário usa o Git para aplicar a correção.
-
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
RESSALVAS
Observe que format-patch
irá omitir a mesclagem dos commits que forem gerados, ainda que eles façam parte do intervalo solicitado. Um simples "patch" não inclui informações suficientes para que a parte receptora reproduza a mesma mesclagem do commit.
GIT
Parte do conjunto git[1]