# Manual do &kdiff3;

## Introdução

### Outra Interface para o Diff?

Existem várias ferramentas de detecção de diferenças. Porquê escolher o &kdiff3;? Deixe que o autor diga porque ele o escreveu.

O &kdiff3; começou porque eu tinha que fazer uma mesclagem difícil. A mesclagem é necessária quando várias pessoas trabalham nos mesmos arquivos de um projeto. Uma mesclagem poderá de alguma forma ser automatizada, quando a ferramenta de mesclagem não só tem os novos arquivos modificados (chamados de 'ramificações' ou 'branches'), mas também o arquivo original (chamado de 'base'). A ferramenta de mesclagem irá escolher automaticamente as modificações que só foram feitas numa das ramificações. Quando vários contribuintes alteram as mesmas linhas, então a ferramenta de mesclagem detecta um conflito que terá que ser resolvido manualmente.

A mesclagem foi então difícil porque um dos colaboradores alterou várias coisas e corrigiu o recuo em vários locais. Outro também alterou muito texto, o que resultou em vários conflitos de mesclagem.

A ferramenta que eu usei então só mostrava as linhas modificadas, mas não o que tinha sido alterado dentro dessas linhas. E não havia nenhuma informação sobre os locais em que só o recuo tinha sido alterado. A mesclagem foi um pequeno pesadelo por isso.

Assim, foi este o início. A primeira versão podia mostrar as diferenças dentro de uma linha e mostrava as diferenças de espaços em branco. Depois, muitas outras funcionalidades foram adicionada para aumentar a utilidade.

Por exemplo, se você quiser comparar algum texto rapidamente, então poderá copiá-lo para a área de transferência e colá-lo noutra janela de diferenças.

Uma funcionalidade que precisou de um grande esforço foi a comparação de pastas e a funcionalidade de mesclagem, o que transformou o programa quase num navegador de arquivos completo.

Espero que o &kdiff3; funcione para você também. Divirta-se!

Joachim Eibl (2003)

### Imagens e Funcionalidades

Esta imagem mostra a diferença entre dois arquivos de texto (usando uma versão antiga do &kdiff3;):

A mesclagem por 3-vias é totalmente suportada. Isto é útil se duas pessoas alterarem o código independentemente. O arquivo original (a base) é usado para ajudar o &kdiff3; a selecionar automaticamente as alterações corretas. O editor de mesclagens abaixo das janelas de diferenças permite-lhe resolver os conflitos, enquanto lhe mostra o resultado que você irá obter. Você até poderá editar o resultado. Esta imagem mostra três arquivos de entrada sendo mesclados:

O &kdiff3; também o ajuda a comparar e a mesclar pastas completas. Esta imagem mostra o &kdiff3; durante a mesclagem de pastas:

### Mais Funcionalidades

#### Visualizador de Diferenças Linha-a-Linha e Caractere-a-Caractere

Usando as possibilidades de um ambiente gráfico a cores, o &kdiff3; mostra exatamente o que é a diferença. Quando você tiver que fazer várias revisões de código, irá gostar disto.

#### Ver as Diferenças de Espaços em Branco de uma Vez

Os espaços e as tabulações que são diferentes aparecem visivelmente. Quando as linhas diferem apenas pelo número de espaços em branco, isto poderá ser visto num instante se olhar para a coluna do resumo do lado esquerdo. (Não há mais problemas quando as pessoas mudam o recuo).

#### Diferenças Triplas

Analise três arquivos e veja no que eles diferem.

As janelas da esquerda/meio/direita são intituladas A/B/C e têm as cores azul/verde/magenta, respectivamente.

Se um dos arquivos for igual e o outro for diferente numa linha, então a cor mostra qual o arquivo que é diferente. A cor vermelha indica que ambos os arquivos são diferentes.

#### Mesclagem Confortável de Dois ou Três Arquivos de Entrada

O &kdiff3; pode ser usado para mesclar dois ou três arquivos de entrada e mesclar automaticamente o máximo possível. O resultado é apresentado numa janela editável em que a maioria dos conflitos poderá ser resolvida com um simples clique do mouse: Selecione os respectivos botões ... nas janelas A/B/C para selecionar a origem que deverá ser usada. Uma vez que esta janela de resultado é um editor, até mesmo os conflitos que necessitem de mais correções poderão ser resolvidos aqui sem necessitarem de outra ferramenta.

#### E ...

- Navegação rápida através de botões.

- Um clique do mouse numa coluna de resumo sincroniza todas as janelas para mostrarem a mesma posição.

- Selecionar e copiar de qualquer janela para colar na janela do resultado da mesclagem.

- Uma coluna de visão geral que mostra onde estão as alterações e os conflitos.

- As cores são ajustáveis de acordo com as suas preferências específicas.

- Um tamanho de tabulação ajustável.

- Uma opção para inserir espaço em vez de tabulações.

- Abertura confortável dos arquivos através de uma janela ou da linha de comando.

- Pesquise strings em todas as janelas de texto com os itens de menu Editar Localizar (&Ctrl;F) e Editar Localizar Próximo (F3).

- Mostrar os números de linha para cada linha.

- Colar o conteúdo da área de transferência e arrastar o texto para uma janela de inserção de diferenças.

- Transparência de rede através do KIO.

- Pode ser usado como visualizador de diferenças no &kdevelop; 3.

- Quebra de linhas para linhas compridas.

- Suporte para o Unicode, UTF-8 e outras codificações.

- Suporte para as línguas escritas da direita-para-esquerda.

- ...

## Comparação e Mesclagem de Arquivos

### Opções da Linha de Comando

#### Comparar 2 arquivos:

    kdiff3 arquivo1 arquivo2

#### Mesclar 2 arquivos:

    kdiff3 arquivo1 arquivo2 -m
       kdiff3 arquivo1 arquivo2 -o resultado

#### Comparar 3 arquivos:

    kdiff3 arquivo1 arquivo2 arquivo3

#### Mesclar 3 arquivos:

    kdiff3 arquivo1 arquivo2 arquivo3 -m
       kdiff3 arquivo1 arquivo2 arquivo3 -o resultado

Repare que o `arquivo1` será tratado como base para o `arquivo2` e o `arquivo3`.

#### Caso especial: Arquivos com o mesmo nome

Se todos os arquivos tiverem o mesmo nome mas estiverem em pastas diferentes, você poderá reduzir o trabalho de escrita se indicar apenas o nome do arquivo para o primeiro parâmetro. Por exemplo:

    kdiff3 pasta1/arquivo pasta2 pasta3

#### Linha de comando para iniciar uma comparação ou mesclagem de pastas:

É bastante semelhante, mas diz respeito agora apenas às pastas.

    kdiff3 pasta1 pasta2
       kdiff3 pasta1 pasta2 -o destino
       kdiff3 pasta1 pasta2 pasta3
       kdiff3 pasta1 pasta2 pasta3 -o destino

Para a comparação e mesclagem de pastas, você poderá continuar a ler aqui.

#### Outras opções da linha de comando

Para mais informações sobre as opções da linha de comando use

    kdiff3 --help

Exemplo do resultado:

    Opções:
      -m, --merge               Mescla o resultado.
      -b, --base arquivo        Arquivo de base explícito. Para compatibilidade com certas ferramentas.
      -o, --output arquivo      Arquivo de resultado. O -m é implícito. P.ex.: -o novo_arquivo.txt
      --out arquivo             O arquivo de resultado, mais uma vez. (Para compatibilidade com certas ferramentas.)
      --noauto                  Ignorar --auto e sempre mostrar a interface.
      --auto                    Sem interface gráfica se todos os conflitos são resolúveis. (Necessita do -o)
      --L1 nome1                Substituto visível do nome do arquivo 1 (base).
      --L2 nome2                Substituto visível do nome do arquivo 2.
      --L3 nome3                Substituto visível do nome do arquivo 3.
      -L, --fname nome          Um substituto visível alternativo para o nome. Use este uma vez para cada arquivo de entrada.
      --cs texto                Substitui uma opção de configuração. Use uma vez para cada opção. P.ex. --cs "AutoAdvance=1"
      --confighelp              Mostra uma lista com as opções de configuração e os valores atuais.
      --config arquivo          Usa um arquivo de configuração diferente.

A opção `--cs` permite-lhe ajustar um valor de configuração que, de outro modo, só é ajustável através das janelas de configuração. Mas tenha em mente que, quando o &kdiff3; terminar, o valor alterado será gravado com as outras opções. Com o `--confighelp`, você poderá descobrir os nomes dos itens disponíveis e dos valores atuais.

Através do `--config`, você poderá indicar um arquivo de configuração diferente. Quando usar frequentemente o &kdiff3; com opções completamente diferentes, isto permitirá mudar rapidamente entre elas.

#### Ignorar as opções da linha de comando

Muitas pessoas querem usar o &kdiff3; com alguns sistemas de controles de versões. Mas quando esse sistema de controle de versões chama o &kdiff3;, usando os parâmetros da linha de comando que o &kdiff3; não reconhece, então o &kdiff3; termina com um erro. O item Integração na janela de configurações permite indicar parâmetros da linha de comando que deverão ser ignorados pelo &kdiff3;. Eles irão aparecer na ajuda de uso, como neste exemplo:

    --xpto                     Ignorado. (Definido pelo usuário.)

Opções da linha de comando a ignorar:

- Uma lista de opções, separadas pelo ponto e vírgula ';'. Quando alguma destas opções aparecer na linha de comando, então o &kdiff3; irá ignorá-la e irá executar sem indicar qualquer erro. (Por padrão é "`u;query;html;abort`").

Quando isto não for suficiente, então recomenda-se que crie um programa que faça a tradução das opções.

### Janela de Abertura

Uma vez que é necessário selecionar vários arquivos, o programa tem uma janela de abertura especial:

A janela de abertura permite editar os nomes dos arquivos à mão, selecionando um arquivo através do navegador dos arquivos pelo botão Arquivo... ou permite escolher os arquivos recentes a partir das listas respectivas. Se abrir a janela de novo, então os nomes atuais irão permanecer nela. O terceiro arquivo de entrada não é obrigatório. Se a entrada para C continuar em branco, então só será efetuada uma análise de diferenças com dois arquivos.

Você poderá também selecionar uma pasta com o botão Pasta.... Se for indicado A como uma pasta, então será iniciada uma comparação/mesclagem de pastas. Se o A se referir a um arquivo, mas o B, o C ou o destino corresponderem a pastas, então o &kdiff3; usa o nome do arquivo em A nas pastas indicadas.

Se a Mesclagem estiver selecionada, então o campo Resultado fica editável. Mas não é obrigatório indicar o nome do arquivo do resultado imediatamente. Você poderá também adiar isto até o salvamento.

O botão Configurar... abre a janela de configurações, para que você possa definir as opções antes de executar a análise.

### Colar e Arrastar Dados

Em algumas ocasiões, você poderá querer comparar partes de um texto que não está em nenhum arquivo próprio. O &kdiff3; também lhe permite colar texto da área de transferência para a janela de inserção de diferenças que esteja em primeiro plano. A análise de diferenças irá ocorrer então. Na janela de abertura, você não irá necessitar de indicar arquivos, fechando-a então com o Cancelar.

Você também poderá usar o 'arrastar e soltar': Arraste um arquivo de um gerenciador de arquivos ou o texto selecionado de um editor e solte-o em uma janela de inserção de diferenças.

Qual é a ideia? Algumas vezes um arquivo contém duas funções semelhantes, mas a verificação sobre as semelhanças entre elas é um grande esforço, se você precisar criar primeiro dois arquivos e depois carregá-los. Assim, poderá simplesmente copiar, colar e comparar as seções relevantes.

Atualmente, você não poderá arrastar nada a partir do &kdiff3;. Só é permitido soltar dados nas janelas de inserção de diferenças.

Alguns editores ainda interpretam o 'arrastar e soltar' em outro programa como o Cortar (em vez do Copiar) e Colar. Os seus dados originais poderão deste modo perder-se.

### Comparar os Arquivos e Interpretar a Informação nas Janelas de Entrada

#### Linha de Informação

No topo de cada janela de texto existe a sua "linha de informação". As linhas de informação das janelas de inserção de diferenças contêm uma letra A, B ou C, o nome do arquivo e o número da primeira linha visível da janela. (Lembre-se que a janela C é opcional). Cada linha de informação aparece com uma cor diferente. (Se as localizações forem muito extensas para caberem, você poderá mover o cursor do mouse para cima da linha de informação, de modo a que apareça uma dica com o nome completo).

Quando tiver selecionado outro arquivo através de navegação ou acabar de editar o nome do arquivo aqui, pressionando &Enter;, o novo arquivo será carregado e comparado com os arquivos já carregados previamente.

#### Coloração

As três janelas de entrada têm atribuídas as letras A, B e C. O A tem uma cor azul, o B verde e o C magenta. (Estas são as cores padrão, mas podem ser alteradas no menu de configuração).

Quando é detectada uma diferença, então a cor mostra qual o arquivo de entrada que é diferente. Quando todos os outros arquivos de entrada diferem, então a cor usada para exprimir isto é a vermelha por padrão (opção Cor do conflito no item Cor na janela de configurações). Este esquema de cores é particularmente útil no caso de três arquivos de entrada, os quais serão vistos na próxima seção (Mesclar).

#### Coluna de Resumo

À esquerda de cada texto está a coluna "resumo". Se ocorrerem diferenças numa linha, então a coluna do resumo mostra a cor respectiva. Para uma diferença por espaços em branco, o resumo fica em xadrez. Para as linguagens de programação em que os espaços em branco não são muito importantes, isto é útil para ver de um modo geral se existe algo de importante modificado. (No C/C++, os espaços em branco só são importantes dentro de cadeias de caracteres, comentários, pré-processador e em algumas outras situações esotéricas.)

A linha vertical que separa a coluna do resumo e o texto é interrompida (tracejada), se o arquivo de entrada não tiver aí nenhuma linha. Quando a mudança de linha estiver ativa, então esta linha vertical aparece ponteada para as linhas repartidas.

#### Coluna de Resumo

Do lado direito, aparece uma coluna de "resumo" à esquerda da barra de rolagem vertical. Ela mostra a coluna de resumo comprimida dos dados de A. Todas as diferenças e conflitos ficam visíveis numa vista rápida. Quando só são usadas duas janelas de entrada, então todas as diferenças aparecem em vermelho, uma vez que cada diferença é também um conflito. Um retângulo preto delimita a parte visível dos dados de entrada. Para as linhas de dados muito compridas, quando o número de linhas de dados é maior do que a altura da coluna de resumo em pixels, então várias linhas de dados de entrada irão compartilhar uma linha de resumo. Um conflito, neste caso, terá então uma prioridade elevada sobre as diferenças simples, que por sua vez têm prioridade sobre a ausência de alterações, assim não se perde nenhuma diferença ou conflito neste caso. Se clicar nesta coluna de resumo, será mostrado o texto correspondente.

#### Alinhar Manualmente as Linhas

Em alguns casos, o algoritmo coloca as linhas erradas após umas às outras. Ou se deseja comparar um pedaço de texto com outro que se encontra numa posição completamente diferente no outro arquivo. Para esses casos, você poderá indicar manualmente ao &kdiff3; para alinhar certas linhas. Marque o texto para o qual deseja melhorar o alinhamento com o mouse, como faria para copiar e colar na primeira visualização de diferenças e, em seguida, escolha o item de menu (&Ctrl;Y). Irá aparecer uma barra laranja na coluna do resumo, após o texto escolhido. Repita isto para a segunda e (se disponível) a terceira janela de diferenças. O &kdiff3; irá calcular imediatamente de novo as diferenças sempre que fizer isto, alinhando as linhas escolhidas. Obviamente, algumas das linhas anteriormente correspondentes poderão não corresponder mais.

Atualmente, a mesclagem não suporta a utilização da ajuda de diferenças manual.

#### Mesclar e Dividir Manualmente Seções de Diferenças

Em alguns casos, o &kdiff3; irá ver seções de diferenças a mais ou a menos para a mesclagem. Nesse caso, você poderá mesclar ou dividir as seções existentes.

Adicione seções novas, selecionando primeiro o texto nas linhas que pertencem em conjunto a qualquer uma das janelas de entrada (como acontece na cópia para a área de transferência). Depois, selecione o item Mesclar Dividir a diferença na seleção, do menu. Serão adicionadas divisões antes da primeira linha e depois da última linha do texto selecionado. Se você só quiser adicionar uma seção, então selecione o texto que começa noutra divisão de seção.

Para juntar as seções, selecione algo nas linhas das seções a juntar, em qualquer uma das janelas de entrada. (Você poderá também juntar diversas seções de uma vez). Depois, selecione o item Mesclar Juntar as diferenças selecionadas do menu.

### Mesclar e a Janela do Editor do Resultado da Mesclagem

A janela do editor do resultado da mesclagem (abaixo das janelas de inserção de diferenças) também tem uma linha de informação no topo que mostra Resultado:, o nome do arquivo e `[Modificado]` se você tiver alterado alguma coisa. Normalmente irá conter algum texto resultante das funcionalidades de mesclagem automática, mas frequentemente irá conter também conflitos.

O salvamento está desativado até que todos os conflitos estejam resolvidos. (Use os botões para Ir para o conflito não resolvido anterior/seguinte para descobrir os conflitos que faltam.)

Com apenas dois arquivos de entrada, todas as diferenças são também conflitos que necessitam ser resolvidos manualmente.

Com três arquivos de entrada, o primeiro arquivo é tratado como a base, enquanto que o segundo e o terceiro contêm as modificações. Quando, em qualquer linha, só o arquivo B ou o C tiverem sido alterados mas não ambos, então será selecionada a origem alterada. Só quando o B e o C alteraram as mesmas linhas é que a ferramenta detecta um conflito que deverá ser resolvido manualmente. Quando o B e o C são iguais mas não são o mesmo que o A, é selecionado o C.

#### A Coluna de Resumo

A janela do editor do resultado da mesclagem também tem uma coluna de resumo à esquerda. Ela mostra a letra do arquivo de entrada para o qual foi selecionada a linha ou nada, se todas as três origens são iguais nessa linha. Para os conflitos, ela mostra um ponto de interrogação "?" e a linha mostra "<Conflito na Mesclagem>", tudo em vermelho. Uma vez que a resolução de conflitos linha a linha poderá levar bastante tempo, as linhas são reunidas em grupos com as mesmas características de diferenças e conflitos. Mas os conflitos só com espaços em branco são separados dos outros conflitos para facilitar a mesclagem dos arquivos em que o recuo foi alterado em várias linhas.

#### Configurar o Grupo Atual e Sincronizar a Posição de Visualização da Mesclagem e Diferenças

Ao clicar na coluna do resumo com o &LMB; em ambas as janelas, o grupo que pertença a essa linha será selecionado em todas as janelas e o início desse grupo será mostrado. Este grupo fica então o "grupo atual". Fica realçado com a opção Cor de fundo do intervalo atual do item Integração na janela de configurações e aparece uma barra preta do lado esquerdo do texto.

#### Escolher as Entras A, B ou C para os Conflitos e Edições Atuais

A barra de botões abaixo do menu contém três botões de seleção que contêm as letras A, B e C. Clique no seletor de entrada para inserir (ou remover se já estiver inserido) as linhas da origem respectiva. Para escolher as linhas de várias entradas, clique nos botões respectivos na ordem necessária. Por exemplo, se quiser que as linhas de B apareçam antes das linhas de A no resultado, clique primeiro em B e depois em A.

Se você usar o botão Ir automaticamente para o próximo conflito não resolvido após a seleção da fonte (veja a seção Avanço automático), deverá desativar isto antes de escolher as linhas de várias entradas ou se quiser editar as linhas após a sua escolha. Caso contrário, o &kdiff3; irá saltar para o próximo conflito após a seleção da primeira entrada.

Normalmente é útil editar diretamente o resultado da mesclagem. A coluna de resumo irá mostrar "m" para cada linha modificada manualmente. Quando, por exemplo, as diferenças estão alinhadas de forma que não seja satisfatório escolher simplesmente as entradas, então poderá marcar o texto necessário e usar a cópia e colagem normais para colocar no resultado da junção.

Algumas vezes, quando uma linha é removida tanto por mesclagem automática como por edição e não fica mais nenhuma linha nesse grupo, então o texto "<Sem linha de origem>" irá aparecer nessa linha. Isto é apenas um substituto para o grupo, quando decidir mudar de ideia e selecionar algum texto de origem de novo. Este texto não irá aparecer no arquivo salvo ou em qualquer seleção que deseje copiar e colar.

O texto "<Conflito na Mesclagem>" irá aparecer na área de transferência se copiar e colar algum texto que tenha uma dessas linhas. Mas ainda tenha cuidado ao fazer isso.

#### Escolher a Entrada A, B ou C para Todos os Conflitos

A mesclagem normal irá começar por resolver os conflitos simples automaticamente. Mas o menu Mesclar oferece algumas ações para outros usos comuns. Se você tiver que selecionar a mesma origem para a maioria dos conflitos, então poderá escolher A, B ou C em qualquer lado ou apenas para os conflitos que continuem ainda por resolver ou então para os conflitos de espaços em branco por resolver. Se quiser decidir cada um dos deltas por si próprio, poderá Passar os deltas para conflitos. Ou, se preferir voltar às escolhas automáticas do &kdiff3;, selecione então a opção Resolver automaticamente os conflitos simples. Nesse caso, o &kdiff3; irá reiniciar a mesclagem. Para as ações que alteram as suas modificações anteriores, o &kdiff3; pedirá uma confirmação antes de prosseguir.

Ao escolher uma das origens para os conflitos que não sejam de espaços em branco e as opções Ignorar os números (tratar como espaço em branco) ou Ignorar os comentários de C/C++ (tratar como espaço em branco) forem usadas, então as alterações nos números ou comentários serão tratadas como espaços em branco também.

#### Mesclagem Automática das Palavras-Chave e do Histórico do Controle de Versões (Registro)

Muitos sistemas de controle de versões tem suporte a palavras-chave especiais no arquivo. (⪚ "`$Date$`", "`$Header$`", "`$Author$`", "`$Log$`" &etc;) Durante o envio de novas versões, o sistema de controle de versões (SCV) muda essas linhas. Por exemplo, o "`$Date$`" passará a "`$Date: 2005/03/22 18:45:01 $`". Uma vez que esta linha será diferente em cada versão do arquivo, seria necessário intervenção manual durante a mesclagem.

O &kdiff3; oferece mesclagem automática para esses itens no item Mesclar da janela de configurações. Para linhas simples que correspondam à opção Mesclar expressão regular automaticamente em todos os arquivos de entrada, o &kdiff3; escolherá a linha de B ou - se disponível - de C. (Além disso, é necessário que as linhas em questão estejam alinhadas na comparação e que a linha anterior não contenha conflitos.) Essa mesclagem automática pode ser executada imediatamente após o início de uma mesclagem (ative a opção Executar mesclagem automática por expressão regular no início da mesclagem) ou posteriormente por meio do item de menu Mesclar Executar mesclagem automática por expressão regular.

A mesclagem automática para o histórico do controle de versões (também chamado de "registro") é também suportada. A mesclagem automática do histórico tanto poderá rodar automaticamente quando iniciar a mesclagem, ativando para tal a opção Mesclar o histórico do controle de versões no início da mesclagem no item Mesclar na janela de configurações ou mais tarde através do item do menu Mesclar Resolver automaticamente os conflitos do histórico.

Normalmente, o histórico do controle de versões começa por uma linha que contém a palavra-chave "`$Log$`". Isto deverá corresponder à opção Expressão regular do início do histórico. O &kdiff3; detecta quais as linhas subsequentes no histórico, analisando os caracteres iniciais que aparecem antes da palavra-chave "`$Log$`". Se também aparecer o mesmo "comentário inicial" nas linhas seguintes, então estas também serão incluídas no histórico.

Durante o envio de cada nova versão, o SCV grava uma linha única que indica a versão, a data e a hora, seguida de linhas com os comentários dos usuários. Essas linhas formam um item de histórico. Esta seção do histórico vai crescendo com o envio de versões novas e os itens mais recentes aparecem no topo (após a linha inicial do histórico).

Quando, em desenvolvimentos paralelos, dois ou mais programadores enviam versões em ramificações diferentes, o histórico da mesclagem irá conter vários itens que aparecem como conflitos na mesclagem das ramificações. Uma vez que a mesclagem deles poderá se tornar muito aborrecida, o &kdiff3; oferece o suporte com duas estratégias possíveis: basta inserir a informação de histórico de ambas as contribuições no topo ou ordenar a informação de histórico do usuário, usando uma chave definida pelo mesmo.

O método basta-inserir-todos-os-itens é mais fácil de configurar. O &kdiff3; só precisa de um método para detectar as linhas que pertencem a um item de histórico. A maioria dos SCV inserem uma linha em branco, após cada item do histórico. Se não existirem mais linhas em branco, então este será um critério suficiente para o &kdiff3;. Basta inserir uma Expressão regular do início do item de histórico em branco no item Mesclar na janela de configurações. Se o critério da linha vazia não for suficiente, você poderá indicar uma expressão regular para detectar o início do item do histórico.

Lembre-se que o &kdiff3; irá remover os itens de histórico duplicados. Se um item de histórico aparecer várias vezes no histórico de um arquivo de entrada, só um irá aparecer no resultado.

Se você quiser ordenar o histórico, então terá que indicar como deverá ser gerada a chave de ordenação. Use parênteses na Expressão regular do início do item de histórico no item Mesclar na janela de configurações para agrupar as partes da expressão regular que deverão mais tarde ser usadas na chave de ordenação. Indique depois a Ordem da chave de ordenação do início do item de histórico, indicando para isso uma lista de números separados por ",", referentes à posição do grupo na expressão regular.

Uma vez que isto não é tão simples de colocar funcionando de início, você poderá testar e melhorar as expressões regulares e gerar as chaves, numa janela dedicada, se clicar no botão Testar as suas expressões regulares.

Exemplo: Considere um histórico como este:

    /**************************************************************************
    ** HISTORY:    $Log: \janela_do_tom\Aplicacao\src\algoritmo-complexo.cpp $
    **
    **     \principal\ramo_integracao_12   2 Abr 2001 10:45:41   ze
    **  Juntou-se a ramificação simao_versao_15.
    **
    **     \principal\ramo_correcao_erros_7\1   30 Mar 2001 19:22:05   pedro
    **  Melhorias na velocidade da sub-rotina convertToMesh().
    **  Correção do estoiro.
    **************************************************************************/

A linha inicial do histórico corresponde à expressão regular "`.*\$Log.*\$.*`". Em seguida, seguem as entradas do histórico.

A linha com a palavra-chave "`$Log$`" começa com dois "*", após os quais se segue um espaço. O &kdiff3; usa o primeiro texto não-branco como "comentários iniciais" e assume que o histórico termina na primeira linha sem esse comentário inicial. Neste exemplo, a última linha termina com um texto que também começa por dois "*" mas, em vez de um espaço, seguem-se mais "*". Como tal, esta linha termina o histórico.

Se a ordenação do histórico não for necessária, a expressão regular da linha inicial da entrada do histórico poderia ser assim. (Esta linha está dividida em duas porque não caberia de outra forma.)

    \s*\\main\\\S+\s+[0-9]+ (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)
     [0-9][0-9][0-9][0-9] [0-9][0-9]:[0-9][0-9]:[0-9][0-9]\s+.*

Para mais detalhes sobre as expressões regulares, veja por favor a documentação da Trolltech sobre expressões regulares. Repare que o "`\s`" (com o "`s`" minúsculo) corresponde a qualquer espaço em branco e o "`\S`" (com o "`S`" maiúsculo) corresponde a qualquer caractere que não seja espaço em branco. No nosso exemplo, o início do item de histórico, contém primeiro a informação da versão com a expressão regular "`\\principal\\\S+`", a data consiste no dia "`[0-9]+`", mês "`(Jan|Fev|Mar|Abr|Mai|Jun|Jul|Ago|Set|Out|Nov|Dez)`" e no ano "`[0-9][0-9][0-9][0-9]`", a hora "`[0-9][0-9]:[0-9][0-9]:[0-9][0-9]`" e, finalmente, o nome de login do programador "`.*`".

Repare nos caracteres do "comentário inicial" (no exemplo "`**`"), que terão já sido removidos pelo &kdiff3; antes de tentar a correspondência; assim, a expressão regular começa com uma correspondência a zero ou mais espaços em branco "`\s*`". Uma vez que os caracteres de comentários poderão ser diferentes para cada arquivo (⪚ o C/C++ usa caracteres de comentários diferentes de um programa em Perl), o &kdiff3; toma conta dos caracteres de comentário iniciais e você não os deverá definir na expressão regular.

Se você precisar de um histórico ordenado, a chave de classificação deverá ser calculada. Para isso, as partes relevantes da expressão regular devem ser agrupadas por parênteses. (Os parênteses extras também podem permanecer se a classificação do histórico estiver desativada.)

    \s*\\main\\(\S+)\s+([0-9]+) (Jan|Fev|Mar|Abr|Mai|Jun|Jul|Ago|Set|Out|Nov|Dez)
     ([0-9][0-9][0-9][0-9]) ([0-9][0-9]:[0-9][0-9]:[0-9][0-9])\s+(.*)

Os parênteses contêm agora `1`. a informação de versão, `2`. dia, `3`. mês, `4`. ano, `5`. hora, `6`. nome. Mas, se pretender ordenar por data e hora, é necessário construir uma chave com os elementos por uma ordem de aparência diferente: Primeiro o ano, seguido do mês, dia, hora, informação de versão e nome. Daí, a ordem da chave de ordenação será "`4,3,2,5,1,6`".

Uma vez que os nomes dos meses não são bons para ordenar (o "`Abr`" viria em primeiro lugar), o &kdiff3; detecta em que ordem os nomes dos meses foram fornecidos e usa esse número em alternativa ("`Abr`"->"`04`"). E, se for encontrado um número puro, será transformado num valor de 4 algarismos com zeros iniciais para ordenar. Finalmente, a chave de ordenação resultante da linha inicial do primeiro item de histórico será:

    2001 04 0002 10:45:41 ramo_integracao_12   tom

Para mais informações, veja também a seção Opções de mesclagem.

### Navegação e Edição

Muita da navegação será feita com as barras de rolagem e com o mouse, mas você poderá também navegar com as teclas. Se clicar em uma das janelas, então poderá usar ps ataçjps &Left;, &Right;, &Up;, &Down;, &PgUp;, &PgDn;, Home, End, &Ctrl;Home e &Ctrl;End como usaria em outros programas. A coluna de resumo ao lado da barra de rolagem vertical dos arquivos de entrada poderá também ser usada para navegar se clicar nela.

Você poderá também usar a roda do mouse para subir ou descer.

No editor do resultado da mesclagem, você poderá também usar as outras teclas para editar. Poderá alternar entre o modo de inserção ou sobreposição com a tecla &Ins;. (Por padrão, está no modo de inserção).

Um clique com o &LMB; em qualquer coluna de resumo irá sincronizar todas as janelas para mostrar o início do mesmo grupo de linhas (tal como é explicado em Configurar o grupo atual e sincronizar a posição da janela de mesclagem e diferença).

A barra de botões também contém sete botões de navegação com os quais poderá saltar para a primeira/última/atual diferença, para a diferença seguinte/anterior (&Ctrl;&Down;/&Ctrl;&Up;), para o conflito seguinte/anterior (&Ctrl;&PgDn;/&Ctrl;&PgUp;) ou para o conflito seguinte/anterior não resolvido. Repare que, para o &kdiff3;, um "conflito" que não foi resolvido automaticamente no início da mesclagem irá permanecer como "conflito", mesmo que resolvido. Daí a necessidade de distinguir os "conflitos não resolvidos".

#### Avanço automático

Existe também um botão Ir automaticamente para o próximo conflito não resolvido após a seleção do código (Avanço Automático). Se ativar esta opção, então sempre que selecionar uma origem, o &kdiff3; irá saltar para o próximo conflito por resolver automaticamente. Isto poderá ajudar quando quiser sempre escolher apenas uma origem. Quando precisar de ambas as origens, ou se quiser editar depois de selecionar, então provavelmente irá querer desligar esta opção. Antes de prosseguir para o próximo conflito por resolver, o &kdiff3; mostra-lhe o efeito da sua escolha durante algum tempo. Este atraso é ajustável no item Mesclar na janela de configurações: Você poderá indicar o Atraso no avanço automático num valor entre 0 e 2 000 milissegundos. Sugestão: Cansado de muitos cliques? - Use um atraso de avanço automático reduzido e os atalhos &Ctrl;1/2/3 para selecionar o A/B/C em muitos conflitos.

### Selecionar, Copiar e Colar

As janelas de entrada não mostram nenhum cursor, assim as seleções precisam ser feitas com o mouse, ao clicar com o &RMB; no início, mantendo o botão do mouse pressionado e indo até ao fim, momento em que solta o botão do mouse de novo. Você poderá também selecionar uma palavra se fizer duplo-clique nela. No editor do resultado da mesclagem poderá também selecionar com o teclado se mantiver a tecla &Shift; pressionada enquanto navega com as teclas de cursores.

Se a seleção ultrapassar o intervalo visível, você poderá passar o mouse por cima das bordas da janela, o que fará com que o &kdiff3; se desloque nessa direção.

Para as seleções muito grandes, você poderá também usar as teclas de navegação, enquanto mantém pressionado o mouse. Por exemplo, use o &PgUp; e o &PgDn; para ir rapidamente para uma dada posição. Na posição final, solte o botão do mouse.

Para selecionar tudo na janela atual, use o item de menu Editar Selecionar tudo (&Ctrl;A).

Para copiar para a área de transferência, você precisa pressionar o botão Copiar (&Ctrl;C ou &Ctrl;&Ins;). Porém, existe uma opção para Copiar automaticamente a seleção no item Editor na janela de configurações. Se esta estiver ativa, então tudo o que selecionar será copiado imediatamente, sem que você tenha de copiar explicitamente. Todavia, preste atenção ao usar isto, uma vez que o conteúdo da área de transferência poderá ser destruído por acidente.

Cortar (&Ctrl;X ou &Shift;∇) copia para a área de transferência e apaga o texto selecionado.

Colar (&Ctrl;V ou &Shift;&Ins;) insere o texto da área de transferência na posição do cursor ou na seleção atual. Se colar numa das janelas de entrada de diferenças, o conteúdo da área de transferência será mostrado nessa janela e a comparação irá reiniciar imediatamente. Isto é útil se quiser pegar rapidamente num pedaço de texto de qualquer local e compará-lo com outra coisa, sem ter que criar arquivos primeiro.

### Salvando

O salvamento só será permitido quando todos os conflitos tiverem sido resolvidos. Se o arquivo já existir e a opção Arquivos de backup estiver ativa no item Pasta na janela de configurações, então o arquivo existente terá o seu nome mudado de modo a ter uma extensão `.orig`, mas se existir um destes arquivos ele será removido. Quando você sair ou iniciar outra análise de diferenças e os dados não tiverem sido salvos ainda, então o &kdiff3; irá perguntar se você deseja salvar, cancelar ou prosseguir sem salvar. (O &kdiff3; não lida com nenhum sinal ('signals') do sistema. Por isso, se fizer um "kill" da instância do &kdiff3;, então os seus dados serão perdidos.)

Os fins de linha são salvos de acordo com o método normal do sistema operacional subjacente. Para os UNIXes, cada linha é terminada com um caractere de 'linefeed' "`\n`", enquanto que nos sistemas baseados em Win32, cada linha termina com um 'carriage-return' + um 'linefeed' "`\r\n`". O &kdiff3; não preserva os fins de linha dos arquivos de entrada, o que também significa que você não deverá usar o &kdiff3; com arquivos binários.

### Procurar strings

Você pode pesquisar uma sequência de caracteres em qualquer janela de texto do &kdiff3;. O item de menu Editar Localizar... (&Ctrl;F) abre uma janela que permite especificar a sequência de caracteres a ser pesquisada. Você também pode selecionar as janelas que devem ser pesquisadas. A pesquisa sempre começará no topo. Use o item de menu Editar Localizar próximo... (F3) para prosseguir para a próxima ocorrência. Se você selecionar a opção para pesquisar em várias janelas, a primeira janela será pesquisada de cima para baixo antes que a pesquisa comece na próxima janela novamente no topo, e assim por diante.

### Impressão

O &kdiff3; suporta a impressão das diferenças do arquivo de texto. O menu Arquivo Imprimir... (&Ctrl;P) abre uma janela que lhe permite selecionar a impressora e ajustar as outras opções.

Existem várias possibilidades para ajustar o intervalo. Devido às diferentes janelas de impressão nos diferentes sistemas operacionais, o método para obter certas seleções de intervalos varia.

Todos:

- Imprime tudo.

Atual:

- Imprime uma página que começa na primeira linha visível da janela. (Nos sistemas sem esta opção, isto poderá ser obtido se indicar o número de página 10000 na impressão.)

Seleção:

- Antes de optar por imprimir, selecione o texto com o mouse (como acontece na cópia e colagem) numa das janelas de entrada das diferenças, para definir a linha inicial e final. Se não foi selecionado nenhum texto numa das janelas de entrada, então esta opção não estará disponível. (Nos sistemas sem esta opção, isto poderá ser conseguido se indicar para imprimir a página 9999.)

Intervalo:

- Indica a primeira e última página.

As outras opções importantes serão retiradas das opções normais:

- Fonte, tamanho da fonte

- Mostrar números de linha

- Quebra de linha

- Cores

- &etc;

A formatação em paisagem (na horizontal) também é recomendada na impressão.

### Opções

As opções e a lista de arquivos recentes serão salvas quando você sair do programa e serão carregadas de novo quando o iniciar. (Menu Configurações Configurar &kdiff3;...).

#### Fonte

Selecione uma fonte monoespaçada. (Em alguns sistemas, esta janela irá também apresentar os tipos de fonte de tamanho variável, mas você não deverá usá-los.)

#### Cores

Editor e visualização das diferenças:

- Cor principal:

- Normalmente preto.

Cor do plano de fundo:

- Normalmente branco.

Cor do plano de fundo das diferenças:

- Normalmente cinza claro.

Cor A:

- Normalmente azul escuro.

Cor B:

- Normalmente verde escuro.

Cor C:

- Normalmente magenta escuro.

Cor de conflito:

- Normalmente vermelho.

Cor de fundo do intervalo atual:

- Normalmente amarelo claro.

Cor de fundo da diferença do intervalo atual:

- Normalmente amarelo escuro.

Cor dos intervalos de diferenças alinhados manualmente:

- Normalmente laranja.

Área de comparação de pasta:

- Cor do arquivo mais recente:

- Normalmente verde.

Cor do arquivo mais antigo:

- Normalmente vermelho.

Cor dos arquivos de tempo intermediário:

- Normalmente amarelo escuro.

Cor dos arquivos faltantes:

- Normalmente preto.

A mudança das cores na comparação das pastas só terá efeito quando iniciar a próxima comparação de pastas.

Nos sistemas com apenas 16 ou 256 cores, alguns dos tons acima descritos não estão disponíveis de forma pura. Nesses sistemas, o botão Padrões irá escolher uma cor pura.

#### Configuração do Editor

Tab insere espaços

- Se isto estiver desativado e você pressionar a tecla , será inserido um caractere de tabulação, caso contrário serão inseridos os espaços com a quantidade apropriada.

Tamanho das tabulações:

- Poderá ser ajustado de acordo com as suas necessidades específicas. Por padrão é igual a `8`.

Recuo automático

- Ao pressionar &Enter; ou Return, o recuo da linha anterior é usada para uma nova linha.

Copiar a seleção automaticamente

- Quando ativo, qualquer seleção é copiada automaticamente para a área de transferência e você não precisa copiá-la explicitamente.

Estilo de fim de linha:

- Ao salvar, o usuário poderá selecionar o estilo do fim de linha que prefere.O valor padrão é a escolha comum para o sistema operacional usado.

#### Configuração das Diferenças

Ao comparar os arquivos, o &kdiff3; tenta primeiro corresponder as linhas iguais em todos os arquivos de entrada. Só durante este passo é que você poderá ignorar os espaços em branco. O segundo passo compara cada uma das linhas. Neste passo, os espaços em branco não serão ignorados. Também durante a mesclagem os espaços em branco não serão ignorados.

Ignorar números (tratar como espaço em branco)

- Por padrão está desligado. Os caracteres dos números ('0'-'9', '.', '-') serão ignorados na primeira parte da análise, na qual é feita a correspondência de linhas. No resultado, as diferenças serão mostradas de qualquer forma, mas serão tratadas como espaços em branco.

Ignorar comentários C/C++ (tratar como espaço em branco)

- Por padrão está desligado. As alterações nos comentários serão tratadas como as alterações nos espaços em branco.

Ignorar maiúsculas/minúsculas (tratar como espaço em branco)

- Por padrão está desligado. As diferenças de capitalização dos caracteres (como o 'A' vs. 'a') serão tratadas como alterações de espaços em branco.

Comando do pré-processamento:

- Veja a próxima seção.

Comando de pré-processamento para correspondência de linhas:

- Veja a próxima seção.

Tentar com persistência (lento)

- Tenta com mais afinco encontrar um delta ainda menor. (Por padrão está ligado). Isto irá ser efetivo provavelmente para os arquivos grandes e complicados. Será também lento para os arquivos muito grandes.

Alinhar B e C para 3 arquivos de entrada

- Tenta alinhar o B e o C ao comparar ou mesclar três arquivos de entrada. Não é recomendado para mesclar porque isto pode ser mais complicado. (Desativado por padrão).

#### Configuração da Mesclagem

Atraso no avanço automático (ms):

- Quando estiver no modo de avanço automático esta opção indica o intervalo de tempo durante o qual mostrar o resultado da seleção antes de saltar para o próximo conflito não resolvido.

Exibir janela de informação

- Exibe uma janela com informações sobre o número de conflitos.

Padrão da mesclagem de espaço em branco com 2/3 arquivos:

- Resolve automaticamente todos os conflitos de espaços em branco, selecionando o arquivo indicado. (Por padrão, é com uma escolha manual). É útil se os espaços em branco não são importantes em muitos dos arquivos. Se você precisar disto apenas ocasionalmente, é melhor usar o Escolher A/B/C nos conflitos de espaços em branco não resolvidos no menu Mesclar. Lembre-se que, se ativar o Ignorar números (tratar como espaço em branco) ou o Ignorar comentários de C/C++ (tratar como espaço em branco, então esta escolha automática também se aplica para os conflitos nos números ou nos comentários.

Expressão regular de mesclagem automática:

- A expressão regular para as linhas onde o &kdiff3; deverá escolher automaticamente uma origem. Veja também a Mesclagem Automática ....

Executar a mesclagem automática via expressão regular ao iniciar a mesclagem

- Se for ativado, o &kdiff3; executa a mesclagem automática com a Expressão regular da mesclagem automática:, quando for iniciada uma mesclagem.

Expressão regular do início do item de histórico:

- A expressão regular do início do item de histórico. Normalmente, esta linha contém a palavra-chave "`$Log$`". Valor padrão: "`.*\$Log.*\$.*`"

Expressão regular do início do item de histórico:

- Um item de mesclagem do histórico consiste em várias linhas. Indique a expressão regular que detecta a primeira linha (sem o comentário inicial). Use os parênteses para agrupar as chaves que deseja usar na ordenação. Se for deixado em branco, o &kdiff3; assume que as linhas em branco separam os itens de histórico. Veja também a Mesclagem automática ....

Ordenação da mesclagem do histórico

- Ativa a ordenação do histórico do controle de versões.

Ordem da chave de ordenação do início do item de histórico:

- Cada par de parênteses usado na expressão regular do item de início de histórico agrupa uma chave que poderá ser usada na ordenação. Indique a lista de chaves (que são numeradas na ordem de ocorrência, a começar em 1), usando o ',' como separador (⪚ "`4,5,6,1,2,3,7`"). Se for deixado em branco, então não será feita nenhuma ordenação. Veja também a Mesclagem automática ....

Mesclar histórico do controle de versões ao iniciar a mesclagem

- Se estiver ativado, o &kdiff3; executa a mesclagem automática do histórico, usando as opções acima mencionadas, quando for iniciada uma junção.

Número máximo de itens do histórico:

- O &kdiff3; limita a lista do histórico ao número de itens indicado. Use `-1` para evitar a limitação. (Por padrão, é igual a `-1`).

Testar as suas expressões regulares

- Este botão mostra uma janela que lhe permite melhorar e testar as expressões regulares acima. Basta copiar os dados respectivos dos seus arquivos para as linhas de exemplo. O Resultado da correspondência: irá mostrar imediatamente se a correspondência é bem sucedida ou não. O Resultado da chave de ordenação: irá mostrar a chave usada no histórico da mesclagem do histórico.

Comando de mesclagem irrelevante:

- Indique um comando próprio, que deverá ser chamado quando o &kdiff3; detectar que, numa mesclagem de três arquivos, o arquivo de B não contribui com dados relevantes que não estivessem já contidos no arquivo em C. O comando é chamado com os três nomes de arquivos como parâmetros. Os dados correspondentes à Expressão regular da mesclagem automática ou no histórico não são considerados relevantes.

Salvar e sair automaticamente na mesclagem sem conflitos

- Se o &kdiff3; foi iniciado para mesclar arquivos a partir da linha de comando e todos os conflitos puderem ser resolvidos sem interação do usuário, salve e encerre automaticamente. (Semelhante à opção de linha de comando `--auto`.)

#### Mesclagem de pasta

Estas opções dizem respeito à análise da pasta e ao tratamento da mesclagem: Veja em Comparação de pastas/Mesclar documentos para mais detalhes.

Existe aqui ainda uma opção que também é relevante para salvar os arquivos únicos:

Arquivos de backup (.orig)

- Quando um arquivo é salvo e já existe uma versão anterior, então a versão original irá mudar para um nome com uma extensão `.orig`. Se já existir um arquivo de cópia de segurança antigo com uma extensão `.orig`, então ele será removido sem ficar nenhuma cópia de segurança.

#### Opções Regionais e da Língua

Usar a mesma codificação para tudo

- As seguintes opções de codificação poderão ser ajustadas separadamente para cada item ou, se esta opção for verdadeira, todos os valores irão usar o primeiro valor.

Nota: A codificação local é "..."

- Acima dos seletores de codificação, aparece uma nota que lhe indica a sua codificação local. (Ela não é ajustável, mas está aqui apenas para informá-lo, no caso de não saber qual é a sua codificação local e tiver que selecioná-la).

Detectar automaticamente

- Esta opção tenta usar o BOM ou metadados de documentos XML/HTML para detectar a codificação. Caso contrário, verificará se uma pequena amostra do início do arquivo pode ser interpretada como UTF-8. Se essa verificação for bem-sucedida, UTF-8 será usado. Caso contrário, o codec selecionado pelo usuário será utilizado. Somente UTF-8 é suportado sem a presença de BOM ou metadados.

Codificação do Arquivo para o A/B/C:

- Ajuste a codificação do arquivo para os arquivos de entrada. Isto provoca algum efeito na forma como os caracteres especiais são interpretados. Uma vez que poderá ajustar cada codificação em separado, você poderá até comparar e mesclar arquivos que foram salvos com codificações diferentes.

Codificação do Arquivo para Mesclagem de Resultado e Salvamento:

- Quando tiver editado um arquivo, você poderá então ajustar a codificação que será usada ao salvar para o disco.

Codificação do Arquivo para os Arquivos de Pré-processador:

- Quando definir pré-processadores, eles poderão não ser capazes de lidar com a sua codificação. (por exemplo: Os seus arquivos estão em Unicode de 16 bits e o seu pré-processador só consegue lidar com &ASCII;de 8 bits). Com esta opção, você poderá definir a codificação do resultado do pré-processador.

Idioma da Esquerda-para-a-Direita:

- Algumas línguas são escritas da direita para a esquerda. Quando esta opção está ativa, o &kdiff3; desenha o texto da direita para a esquerda nas janelas de diferenças dos arquivos de entrada e na janela do resultado da junção. Repare que, se iniciar o &kdiff3; com a opção da linha de comando `--reverse`, então toda a disposição será feita também da direita para a esquerda. (Esta é uma funcionalidade oferecida pelo &Qt;.)

  Esta documentação foi escrita assumindo que esta opção ou o layout inverso estão desativados. Portanto, algumas referências a "esquerda" ou "direita" devem ser substituídas por seus respectivos equivalentes se você usar essas opções.

#### Diversos

(Estas opções e ações estão disponíveis nos menus ou na barra de botões.)

Opções da vista geral:

- Estas opções só estão disponíveis quando você compara três arquivos. No modo normal, todas as diferenças são mostradas na coluna de resumo codificada a cores. Mas, em alguns casos, você está especialmente interessado nas diferenças entre apenas dois desses três arquivos. Se selecionar "A vs. B", "A vs. C" ou "B vs. C" na coluna de resumo irá aparecer uma segunda coluna com a informação necessária ao lado do resumo normal.

Quebrar linhas nas exibições de diferenças

- Quebra as linhas quando o seu tamanho exceder a largura de uma janela.

Mostrar a Janela A/B/C:

- Em algumas vezes, você poderá usar melhor o espaço na tela para as linhas compridas. Oculte as janelas que não são importantes. (No menu "Janelas".)

Alternar a orientação da separação

- Define se as janelas de diferenças são mostradas uma ao lado da outra (a A à esquerda da B, que está à esquerda da C) ou uma por cima da outra (a A sobre a B, que está sobre a C). Isto também deverá ajudar para as linhas compridas (No menu Janela).

Mesclar arquivo atual

- Funciona se você só comparar dois arquivos. Um único clique começa a mesclagem e usa o nome do último arquivo de entrada como nome do arquivo do resultado por padrão. (Quando isto for usado para reiniciar uma mesclagem, então o nome do arquivo do resultado será mantido.)

Exibir espaço em branco

- Desligue isto para suprimir o realce das alterações apenas nos espaços em branco no texto ou nas colunas de vista geral. (Lembre-se que isto também se aplica às alterações nos números ou comentários se as opções Ignorar números (tratar como espaço em branco) ou Ignorar comentários de C/C++ (tratar como espaço em branco) estiverem ativas.)

Exibir caracteres de espaço e tabulação

- Algumas vezes os espaços e tabulações visíveis são incômodos. Você poderá com isto desativar esta funcionalidade.

Exibir números de linha

- O usuário pode selecionar se os números de linhas são mostrados para os arquivos de entrada.

#### Configurar os Atalhos de Teclado

Atualmente, só a versão para &frameworks; suporta os atalhos de teclado configuráveis pelo usuário. (No menu Configurações Configurar atalhos...)

### Comandos do Pré-processador

O &kdiff3; suporta duas opções do pré-processador.

Comando do pré-processamento:

- Quando for lido qualquer arquivo, ele será encaminhado através deste comando externo. O resultado deste comando será visível em vez do arquivo original. O usuário poderá criar o seu próprio pré-processador que corresponda às suas necessidades específicas. Use isto para cortar partes desnecessárias do arquivo ou para corrigir automaticamente o recuo, &etc;

Comando de pré-processamento para correspondência de linhas:

- Quando for lido qualquer arquivo, ele será encaminhado através deste comando externo. Se um comando de pré-processador (ver acima) for também indicado, então o resultado do pré-processador é a entrada para o pré-processador de correspondência de linhas. O resultado só será usado durante a fase de correspondência de linhas da análise. Você poderá escrever o seu próprio pré-processador que corresponda às suas necessidades específicas. Cada linha de entrada terá que ter uma linha de resultado correspondente.

A ideia é permitir ao usuário uma maior flexibilidade ao configurar o resultado das diferenças. Mas isto necessita de um programa externo e muitos dos usuários não querem escrever um. As boas notícias são que, muitas das vezes, o `sed` ou o `perl` se encarregarão disso.

Exemplo: Caso de teste simples: Considere o arquivo a.txt (6 linhas):

    aa
          ba
          ca
          da
          ea
          fa

E o arquivo b.txt (3 linhas):

    cg
          dg
          eg

Sem um pré-processador, as seguintes linhas seriam colocadas lado a lado:

    aa - cg
          ba - dg
          ca - eg
          da
          ea
          fa

Isso provavelmente não é desejado, já que a primeira letra contém a informação realmente interessante. Para ajudar o algoritmo de correspondência a ignorar a segunda letra, podemos usar um comando de pré-processador de correspondência de linhas que substitui 'g' por 'a':

    sed 's/g/a/'

Com esse comando, o resultado da comparação seria:

    aa
          ba
          ca - cg
          da - dg
          ea - eg
          fa

Internamente, o algoritmo de correspondência vê os arquivos após executar a linha de correspondência do pré-processador , mas na tela o arquivo permanece inalterado. (O pré-processador normal também alteraria os dados na tela.)

#### Fundamentos do `sed`

Esta seção só introduz algumas funcionalidades muito básicas do `sed`. Para mais informações veja as páginas info:/sed ou https://www.gnu.org/software/sed/manual/html_mono/sed.html. Existe uma versão pré-compilada para o &Windows; em http://unxutils.sourceforge.net. Repare no fato de que os exemplos a seguir assumem que o comando `sed` está numa pasta referida pela sua variável de ambiente `PATH`. Se não for este o caso, você terá que indicar a localização absoluta completa para o comando.

Neste contexto, apenas o comando substituto `sed` é usado:

    sed 's/EXPRESSÃO REGULAR/SUBSTITUIÇÃO/FLAGS'

Antes de usar um novo comando no &kdiff3;, você deve primeiro testá-lo em um console. Aqui, o comando `echo` é útil. Exemplo:

    echo abrakadabra | sed 's/a/o/'
       -> obrakadabra

Este exemplo mostra um comando sed muito simples que substitui a primeira ocorrência de "a" por "o". Se você quiser substituir todas as ocorrências, você precisa da flag "g":

    echo abrakadabra | sed 's/a/o/g'
       -> obrokodobro

O símbolo "|" é o comando de pipe que transfere a saída do comando anterior para a entrada do comando seguinte. Se você quiser testar com um arquivo mais longo, pode usar `cat` em sistemas como o &UNIX; ou `type` em sistemas como o &Windows;. O comando `sed` fará a substituição para cada linha.

    cat arquivo | sed opções

#### Exemplos de uso do `sed` no &kdiff3;

##### Ignorar Outros Tipos de Comentários

Atualmente, o &kdiff3; entende apenas comentários C/C++. Usando a opção Comando de pré-processador de correspondência de linha: você também pode ignorar outros tipos de comentários, convertendo-os em comentários C/C++.

Exemplo: Para ignorar comentários que começam com "`#`", você gostaria de convertê-los para "`//`". Observe que você também deve habilitar a opção Ignorar comentários C/C++ (tratar como espaço em branco) para obter o efeito desejado. Um comando de pré-processador apropriado para correspondência de linhas seria:

    sed 's/#/\/\//'

Como para o comando `sed` o caractere "`/`" tem um significado especial, é necessário colocar o caractere "`\`" antes de cada "`/`" na string de substituição. Às vezes, o caractere "`\`" é necessário para adicionar ou remover um significado especial de certos caracteres. As aspas simples (') são importantes apenas ao testar no shell de comando, pois, caso contrário, ele tentará processar alguns caracteres. O &kdiff3; não faz isso, exceto para as sequências de escape '`\"`' e '`\\`'.

##### Diff sem Distinguir Capitalização

Use o seguinte Comando de pré-processador de correspondência de linhas: para converter toda a entrada em maiúsculas:

    sed 's/\(.*\)/\U\1/'

Aqui o "`.*`" é uma expressão regular que corresponde a qualquer texto e, no seu contexto, irá corresponder a todos os caracteres da linha. O "`\1`" no texto de substituição refere-se ao texto correspondente ao primeiro par de "`\(`" e "`\)`". O "`\U`" converte o texto inserido para maiúsculas.

##### Ignorar palavras-Chave do controle de versões

O CVS e outros sistemas de controle de versões usam várias palavras-chave para inserir texto gerado automaticamente (info:/cvs/Keyword substitution). Todas elas seguem o padrão "`$PALAVRACHAVE texto gerado$`". É preciso agora um comando pré-processador de correspondência de linhas que remova apenas o texto gerado:

    sed 's/\$\(Revision\|Author\|Log\|Header\|Date\).*\$/\$\1\$/'

O "`\|`" separa as possíveis palavras-chave. Você pode querer modificar esta lista de acordo com suas necessidades. O "`\`" antes do "`$`" é necessário porque, caso contrário, o "`$`" corresponde ao final da linha.

Ao experimentar com o `sed`, você poderá vir a compreender e até a gostar destas expressões regulares. Elas são úteis porque existem muitos outros programas que suportam algumas coisas desse gênero.

##### Ignorar os Números

A indiferença em relação aos números é de fato uma opção incorporada. Mas, como outro exemplo, seria assim como iria ficar como um comando do pré-processador da correspondência de linhas.

    sed 's/[0123456789.-]//g'

Qualquer caractere entre '`[`' e '`]`' é uma correspondência e será substituído por nada.

##### Ignorar Certas Colunas

Em algumas ocasiões um determinado texto tem uma formatação muito restrita e contém colunas que deseja sempre ignorar, enquanto que existem outras colunas que deseje preservar para análise. No exemplo a seguir, as primeiras cinco colunas (caracteres) são ignoradas, as próximas dez são preservadas, depois as próximas cinco colunas serão ignoradas de novo e o resto da linha é preservada.

    sed 's/.....\(..........\).....\(.*\)/\1\2/'

Cada ponto '`.`' corresponde a qualquer caractere individual. Os "`\1`" e "`\2`" na string de substituição referem-se ao texto correspondente dentro do primeiro e segundo par de "`\(`" e "`\)`", denotando o texto a ser preservado.

##### Combinar várias substituições

Em algumas situações você deseja aplicar várias substituições de uma vez. Você poderá então usar o ponto e vírgula '`;`' para separar uma da outra. Exemplo:

    echo abracadabra | sed 's/a/o/g;s/\(.*\)/\U\1/'
       -> OBROCODOBRO

##### Usar o `perl` em vez do `sed`

Em vez de `sed` você pode querer usar algo como `perl`.

    perl -p -e 's/EXPRESSÃO REGULAR/SUBSTITUIÇÃO/FLAGS'

Mas alguns detalhes são diferentes em `perl`. Observe que, enquanto `sed` exigia "`\(`" e "`\)`", `perl` requer o mais simples "`(`" e "`)`" sem o prefixo '`\`'. Exemplo:

    sed 's/\(.*\)/\U\1/'
       perl -p -e 's/(.*)/\U\1/'

#### Ordem de Execução de Pré-processadores

Os dados são encaminhados através de todos os pré-processadores internos e externos na seguinte ordem:

- Pré-processador normal,

- Pré-processador de correspondência de linhas,

- Ignorar capitalização (tratar como espaço em branco) (conversão para maiúsculas),

- Detecção de Comentários de C/C++,

- Ignorar números (tratar como espaço em branco),

- Ignorar os espaços em branco

Os dados após o pré-processador normal serão preservados para a apresentação e para a mesclagem. As outras operações só modificam os dados que o algoritmo para a correspondência de linhas nas diferenças vê.

Nos casos raros em que você usa um pré-processador normal, repare que o pré-processador da correspondência de linhas vê o resultado no pré-processador normal como dados de entrada.

#### Aviso

Os comandos do pré-processador são normalmente muito úteis, mas como acontece com qualquer opção que modifica os seus textos ou oculta algumas diferenças automaticamente, você poderá ignorar certas diferenças e, no pior dos casos, destruir dados importantes.

Por esse motivo, durante uma mesclagem, se um comando de pré-processador normal estiver sendo usado, o &kdiff3; informará isso e perguntará se ele deve ser desativado ou não. Mas ele não avisará se a opção Comando de pré-processador de correspondência de linhas: estiver ativa. A mesclagem não será concluída até que todos os conflitos sejam resolvidos. Se você desativou o item de menu Visualização de diferenças Mostrar espaços em branco, as diferenças que foram removidas com a opção Comando de pré-processador de correspondência de linhas: também ficarão invisíveis. Se o botão Salvar permanecer desativado durante uma mesclagem (devido a conflitos restantes), certifique-se de ativar o item de menu Visualização de diferenças Mostrar espaços em branco. Se você não quiser mesclar essas diferenças menos importantes manualmente, você pode selecionar o item de menu Mesclar Escolher [A|B|C] para todos os conflitos de espaços em branco não resolvidos.

## Comparação e mesclagem de pastas com o &kdiff3;

### Introdução à comparação ou mesclagem de pastas

Normalmente, os programadores precisam de modificar vários arquivos numa pasta para atingir os seus fins. Para isso, o &kdiff3; também lhe permite comparar e mesclar várias pastas de forma recursiva!

Ainda que a comparação e mesclagem de pastas pareça ser bastante óbvia, existem vários detalhes que o usuário deverá conhecer. O mais importante é, obviamente, o fato de que vários arquivos poderão ser afetados por cada operação. Se você não tiver cópias de segurança dos seus dados originais, então poderá ser muito difícil ou mesmo impossível voltar ao estado original. Por isso, antes de começar uma junção, certifique-se de que os seus dados estão a salvo e que é possível voltar atrás. Se cria um pacote ou usa um sistema de controle de versões é uma decisão sua, mas mesmo os programadores experientes e os integradores precisam do código antigo e do novo. E repare que até ao autor do &kdiff3; tenta fazer o seu melhor, mas não pode garantir que não existam erros. De acordo com a GPL da &GNU;, não existe NENHUMA GARANTIA de qualquer forma para este programa. Por isso, seja humilde e tenha sempre em mente:

> Errar é humano, mas para realmente piorar as coisas é preciso um computador.

Por isso, este é o programa que poderá fazer isto por você: o &kdiff3; ...

- ... lê e compara duas ou três pastas recursivamente,

- ... toma um cuidado especial com as ligações simbólicas,

- ... permite-lhe navegar nos arquivos com um duplo-clique do mouse,

- ... propõe para cada item uma operação de mesclagem, que poderá alterar antes de iniciar a mesclagem de pastas,

- ... permite-lhe simular a mesclagem e lista as ações que iriam acontecer, sem fazer nada de fato,

- ... permite-lhe fazer realmente a mesclagem, possibilitando também a você interagir nas situações em que é necessária uma interação manual,

- ... permite-lhe executar a operação selecionada para todos os itens (tecla F7) ou para o item selecionado (tecla F6),

- ... permite-lhe continuar a mesclagem depois de uma interação manual com a tecla F7,

- ... cria opcionalmente cópias de segurança com a extensão `.orig`,

- ...

### Iniciar a comparação ou mesclagem de pastas

Isto é bastante semelhante à mesclagem e comparação simples com arquivos únicos. O usuário apenas terá que indicar nomes de pastas na linha de comando ou na janela de abertura de arquivos.

#### Comparar/Mesclar duas pastas:

    kdiff3 pasta1 pasta2
       kdiff3 pasta1 pasta2 -o destino

Se não for indicada nenhuma pasta de destino, então o &kdiff3; irá usar a `pasta2`.

#### Comparar/Mesclar estas pastas:

    kdiff3 pasta1 pasta2 pasta3
       kdiff3 pasta1 pasta2 pasta3 -o destino

Quando forem mescladas três pastas, então a `pasta1` será usada como a base para a mesclagem. Se não for indicada nenhuma pasta de destino, então o &kdiff3; irá usar a `pasta3` como pasta de destino para a mesclagem.

Repare que só a comparação é que começa automaticamente, não a mesclagem. Para isso, você terá que selecionar primeiro um item do menu ou a tecla F7. (Mais detalhes posteriormente.)

### Informação visível da mesclagem de pastas

Ao ler as pastas, aparece uma mensagem que o informa do progresso. Se você interromper a pesquisa das pastas, então só os arquivos que tenham sido comparados até então serão listados.

Quando a pesquisa de pastas estiver completa, então o &kdiff3; irá mostrar uma lista com os resultados restantes, ...

... e os detalhes sobre o item selecionado atualmente à direita:

#### A Coluna do Nome

Cada arquivo e pasta encontrado durante a pesquisa é aqui mostrado numa árvore. Você poderá selecionar um item se clicar nele uma vez com o mouse.

As pastas estão fechadas por padrão. Você poderá expandi-las e fechá-las se clicar no "+"/"-" ou se fizer duplo-clique no item ou ainda usando as teclas de cursores &Left;/&Right;. O menu Pasta também contém duas ações Fechar todas as subpastas e Expandir todas as subpastas, com as quais poderá fechar ou abrir todas as subpastas de uma vez.

Se fizer duplo-clique num item de um arquivo, então a comparação do arquivo irá começar e irá aparecer a janela de diferenças do arquivo.

A imagem na coluna do nome reflete o tio de arquivo na primeira pasta (A). Poderá ser um dos seguintes:

- Arquivo normal

- Pasta normal (imagem de pasta)

- Ligação para um arquivo (imagem de arquivo com uma seta de ligação)

- Ligação para uma pasta (imagem de pasta com uma seta de ligação)

Se o tipo de arquivo for diferente nas outras pastas, então isso é visível nas colunas A/B/C e na janela que mostra os detalhes sobre o item selecionado. Repare que, neste caso, não poderá ser selecionada nenhuma operação de mesclagem automaticamente. Ao iniciar a junção, então o usuário será informado dos problemas desse tipo.

#### As Colunas A/B/C e o Esquema de Cores

Como pode ser visto na imagem acima, as cores vermelha, verde, amarela e preta são usadas nas colunas A/B/C.

- Preto: O item não existe nesta pasta.

- Verde: Item mais recente.

- Amarelo: Mais antigo que o verde, mais recente que o vermelho.

- Vermelho: O item mais antigo.

Contudo, para os itens que forem idênticos na comparação, a sua cor é também idêntica mesmo que a idade seja diferente.

As pastas são consideradas iguais se todos os itens que contêm forem idênticos. Nesse caso, elas terão a mesma cor. Porém, a idade de uma pasta não é levada em consideração de acordo com a sua cor.

A ideia do autor para este esquema de coloração veio do `dirdiff`. As cores lembram as cores de uma folha que é verde quando é nova, vai-se tornando amarela com o tempo e é vermelha quando é antiga.

#### A Coluna de Operação

Depois de comparar as patas, o &kdiff3; avalia também uma proposta para uma operação de mesclagem. Ela é mostrada na coluna de Operação. O usuário poderá modificar a operação se clicar na operação que deseja alterar. Irá aparecer um pequeno menu que lhe permite selecionar uma operação para esse item (Você poderá também selecionar as operações mais necessárias através do teclado. O &Ctrl;1/2/3/4/∇ irá selecionar o A/B/C/Mesclar/Remover, respectivamente, se estiver disponível.) Esta operação será executada durante a junção. Depende do item e do modo de mesclagem em que se encontra e de que operações estão disponíveis. O modo de mesclagem é um dos seguintes

- Mesclagem de três pastas (a A é tratada como a base mais antiga de ambas).

- Mesclagem de duas pastas.

- Modo de sincronização de duas pastas (ativado com a opção Sincronizar pastas).

Na mesclagem de três pastas, a proposta de operação será: Se para um item ...

- ... todas as três pastas forem iguais: Copiar do C

- ... o A e o C são iguais mas o B não: Copiar a partir do B (ou se o B não existir, remover o destino se existir)

- ... o A e o B são iguais mas o C não: Copiar a partir do C (ou se o C não existir, remover o destino se existir)

- ... o B e o C são iguais mas o A não: Copiar a partir do C (ou se o C não existir, remover o destino se existir)

- ... só o A existir: Remover o destino (se existir)

- ... só B existir: Copiar de B

- ... só C existir: Copiar de C

- ... A, B e C não são iguais: Mesclar

- ... o A, o B e o C não tiverem o mesmo tipo de arquivo (⪚, o A é uma pasta e o B um arquivo): "Erro: Tipo de arquivos em conflito". Enquanto existirem itens nesta situação, a mesclagem de pastas não poderá começar.

Na mesclagem de duas pastas, a proposta de operação será: Se para um item ...

- ... ambas as pastas forem iguais: Copiar de B

- ... A existe, mas não B: Copiar de A

- ... B existe, mas não A: Copiar de B

- ... A e B existem mas não são iguais: Mesclar

- ... o A e o B não tiverem o mesmo tipo de arquivo (⪚ o A é uma pasta e o B um arquivo): "Erro: Tipos de arquivo em conflito". Enquanto existirem itens nesta situação, a mesclagem de pastas não poderá começar.

O modo de sincronização só está ativo se forem indicadas duas pastas e não se não for indicado nenhum destino explícito, assim como a opção Sincronizar pastas terá que estar ativa. Nesse caso, o &kdiff3; irá selecionar uma operação padrão, de modo a que ambas as pastas fiquem iguais no fim. Se, para um item ...

- ... ambas as pastas forem iguais: Não será feito nada.

- ... A existe, mas não B: Copiar A para B

- ... B existe, mas não A: Copiar B para A

- ... o A e o B existirem, mas não forem iguais: Mesclar e guardar o resultado em ambas as pastas. (Para o usuário, o nome do arquivo salvo visível será o B, mas o &kdiff3; irá copiar o B também para o A.)

- ... o A e o B não tiverem o mesmo tipo de arquivo (⪚ o A é uma pasta e o B um arquivo): "Erro: Tipos de arquivo em conflito". Enquanto existirem itens nesta situação, a mesclagem de pastas não poderá começar.

Quando duas pastas forem reunidas e a opção Copiar o mais recente em vez de mesclar estiver selecionada, então o &kdiff3; irá olhar para as datas e irá optar por escolher o arquivo mais recente. Se os arquivos não forem iguais mas tiverem datas iguais, então a operação irá conter "Erro: As datas são iguais mas os arquivos não.". Enquanto esses itens existirem a mesclagem de pastas não poderá começar.

#### A Coluna de Estado

Durante a mesclagem, os arquivos serão processados um após o outro. A coluna de estado irá mostrar Terminado para os itens em que a operação de mesclagem foi bem sucedida e outros textos se algo ocorreu de inesperado. Quando se terminar uma junção, o usuário deverá então fazer uma última verificação para confirmar se o estado de todos os itens é aceitável.

#### Colunas de Estatísticas

Quando o modo de comparação de arquivos Análise completa estiver ativo nas opções, então o &kdiff3; irá mostrar colunas extra que contêm o número de conflitos não resolvidos, de espaços em branco e dos outros conflitos. (A coluna de Resolvido só irá aparecer ao comparar ou ao mesclar três pastas.)

#### Selecionar os Arquivos Listados

Diversas opções influenciam os arquivos que são listados aqui. Algumas estão acessíveis na janela de configuração. O menu Pasta contém os itens:

- Mostrar arquivos idênticos: Os arquivos que foram detectados como iguais em todas as pastas de entrada.

- Mostrar arquivos diferentes: Os arquivos que existem em duas ou mais pastas, mas que não são iguais entre si.

- Mostrar arquivos apenas em A: Os arquivos que existem apenas em A, mas não em B ou C.

- Mostrar arquivos apenas em B: Os arquivos que existem apenas em B, mas não em A ou C.

- Mostrar arquivos apenas em C: Os arquivos que existem apenas em C, mas não em A ou B.

Ative apenas as opções Mostrar para os itens que deseja listar. Se, por exemplo, quiser listar apenas os itens que existem ou em A ou em B, mas não em ambos, você terá de ativar o Mostrar arquivos apenas em A e Mostrar arquivos apenas em B e desativar todos os outros (Mostrar arquivos idênticos, Mostrar arquivos diferentes, Mostrar arquivos apenas em C). A lista será atualizada imediatamente para refletir as alterações.

Estas opções também se aplicam nas pastas, com uma exceção: Se desativar o Mostrar arquivos diferentes não irá ocultar as pastas por completo. Isto só irá funcionar para os arquivos dentro delas.

Lembre-se que, destas opções, só a Mostrar arquivos idênticos é persistente. As outras ficam ativas ao iniciar o &kdiff3;.

### Fazer uma mesclagem de pastas

O usuário tanto poderá reunir o item selecionado no momento (arquivo ou pasta) ou todos os itens. Quando tiver feito todas as suas opções de operação (em todas as subpastas também), aí então poderá iniciar a mesclagem.

Observe que, se não tiver indicado explicitamente uma pasta de destino, então o destino será o C no modo de três pastas, o B no modo de mesclagem de duas pastas e no modo de sincronização será o A e/ou o B.

Se você tiver indicado uma pasta de destino, certifique-se também de que todos os itens que deverão estar no resultado, estão na árvore respectiva. Existem algumas opções que fazem com que certos itens sejam omitidos na comparação e mesclagem de pastas. Assinale estas opções para evitar surpresas desagradáveis:

- Pastas recursivas: Se estiver desligada, então os itens em todas as subpastas não serão tratados.

- Padrão/Anti-padrão: Inclui/exclui os itens que correspondam ao padrão

- Excluir arquivos ocultos

- Mostrar opções (Mostrar arquivos iguais/diferentes, Arquivos apenas em A/B/C)

Se você mudar a configuração, para mostrar mais arquivos, é preciso fazer uma nova pesquisa, com o menu Pasta Pesquisar de novo. (A razão para isso é que o &kdiff3; omite a comparação dos arquivos suprimidos por estes critérios.) Se você mudou os seus padrões de arquivos e pastas para excluir os arquivos, então a lista de arquivos será imediatamente atualizada, ao fechar a janela de opções.

Lembre-se que, quando gravar numa pasta completamente nova, normalmente também irá querer copiar os arquivos iguais. Nesse caso, ative a opção Mostrar arquivos iguais. Se a sua pasta de destino é uma das entradas, então não será necessário, porque o arquivo já estará lá.

Se estiver satisfeito até agora, o resto é simples.

Para mesclar todos os itens: Selecione Iniciar/Continuar a mesclagem da pasta no menu Pasta ou pressione F7 (que é o atalho). Para mesclar apenas o item atual: Selecione Executar operação no item atual ou pressione F6.

Se, devido à existência de tipos de arquivo em conflito, ainda permanecerem alguns itens com operações inválidas, então irá aparecer uma mensagem onde serão evidenciados esses itens, para que possa selecionar uma operação válida para cada item.

Se você mesclar todos os itens, irá aparecer uma janela que lhe apresenta as opções Fazê-lo, Simulá-lo e Cancelar.

- Selecione Simulá-lo se quiser ver o que seria feito sobre o item sem aplicar de fato as modificações. Será apresentada uma lista descritiva com todas as operações.

- Caso contrário, selecione Fazê-lo para iniciar de fato a mesclagem.

Nesse caso, o &kdiff3; irá executar a operação indicada para todos os itens. Se for necessária alguma intervenção manual (na mesclagem de arquivos simples), então irá aparecer uma janela de mesclagem (ver a imagem grande).

Quando tiver terminado um arquivo, selecione de novo Iniciar/Continuar a mesclagem da pasta ou a tecla F7. Se não tiver ainda salvo nada, irá aparecer uma janela pedindo-lhe isso. Aí, o &kdiff3; irá passar ao próximo item.

Quando o &kdiff3; encontrar um erro, ele indicará tal facto e irá mostrar a informação descritiva do estado. No fundo desta lista, existirão algumas mensagens de erro que deverão ajudá-lo a compreender a causa do problema. Quando continuar a mesclagem (com a tecla F7), o &kdiff3; indicará a opção para repetir ou saltar o item que causou o problema. Isto significa que, antes de continuar, você poderá escolher outra operação ou resolver o problema por outros meios.

Quando a mesclagem estiver completa, o &kdiff3; informará então com uma mensagem.

Se alguns dos itens foram mesclados individualmente, então o &kdiff3; irá recordar isto (enquanto esta sessão de mesclagem prosseguir) e não os juntará de novo, até que a mesclagem para todos os itens tenha sido executada. Mesmo quando a mesclagem tenha sido ignorada ou não tenha sido salvo nada, estes itens irão contar como completos. Só quando tiver alterado a operação de mesclagem é que o estado de Pronto do item será removido e ele poderá ser mesclado de novo.

### Opções para comparar e mesclar pastas

As preferências do &kdiff3; (no menu Configurações Configurar &kdiff3;...) têm agora uma seção intitulada "Mesclagem de Pastas" com as seguintes opções:

Pastas recursivas

- Indica se você deseja pesquisar as pastas de forma recursiva.

Padrão(ões) de arquivos:

- Somente os arquivos que correspondam ao padrão ou padrões aqui indicados é que serão colocados na árvore. Poderá ser indicado mais de um padrão através do separador ponto e vírgula ";". São considerados caracteres especiais válidos o '*' e o '?'. (⪚ "`*.cpp;*.h`"). Por padrão, este campo é igual a "*". As pastas não precisam corresponder a este padrão.

Anti-padrão(ões) de arquivos:

- Os arquivos que correspondam ao padrão ou padrões aqui indicados serão excluídos da árvore. Poderá ser indicado mais de um padrão através do separador ponto e vírgula ";". São considerados caracteres especiais válidos o '*' e o '?'. Por padrão, este campo é igual a "`*.orig;*.o;*.obj`".

Anti-padrão(ões) de pastas:

- As pastas que correspondam ao padrão ou padrões aqui indicados serão excluídas da árvore. Poderá ser indicado mais de um padrão através do separador ponto e vírgula ";". São considerados caracteres especiais válidos o '*' e o '?'. Por padrão, este campo é igual a "`CVS;deps;.svn`".

Usar arquivo ignorar

- Ignora os arquivos e pastas que são também ignorados pelo seu sistema de controle de versões. Muitos dos arquivos gerados automaticamente são ignorados usando listas específicas. A grande vantagem é que esta funcionalidade é específica para cada pasta através de um arquivo de configuração local. (Veja a documentação do sistema de controle de versão para mais detalhes.)

Encontrar arquivos e pastas ocultos

- Em alguns sistemas de arquivos, existe um atributo "Oculto". Em outros sistemas, um nome de arquivo que comece por "." faz com que ele seja considerado oculto. Esta opção permite-lhe decidir se deve incluir estes arquivos na árvore ou não. Por padrão, são incluídos.

Seguir links para arquivos

- Para as ligações aos arquivos: Quando a opção estiver desativada, as ligações simbólicas serão comparadas. Caso contrário, serão comparados os arquivos para os quais apontam as ligações. Por padrão, a opção está desligada.

Seguir links para pasta

- Para as ligações a pastas: Quando a opção estiver desativada, as ligações simbólicas serão comparadas. Se estiver ativa, então a ligação será tratada como uma pasta e será pesquisada recursivamente. (Lembre-se que o programa não verifica se a ligação é "recursiva". Por isso, se uma pasta contiver por exemplo uma ligação para ela própria irá causar um ciclo infinito, pelo que ao fim de algum tempo a pilha estoura ou toda a memória será usada e o programa irá estourar deste modo). Por padrão, a opção está desligada.

Distinguir maiúsculas/minúsculas na comparação de nomes de arquivos

- Por padrão, é falso no &Windows; e verdadeiro nos outros sistemas operacionais.

Modo de Comparação de Arquivos:

- Comparação binária

- Este é o modo de comparação de arquivos padrão.

Análise completa

- Faz uma análise completa de cada arquivo e mostra os resultados nas colunas de informação das estatísticas. (O número de conflitos Resolvido, Não resolvido, Não em branco e Em branco). A análise completa é mais lenta que uma simples comparação binária e é muito mais lenta se for usada em arquivos que não contenham texto. (Indique os tipos de anti-padrões necessários.)

Confiar no tamanho e na data de modificação (inseguro)

- Se comparar pastas grandes numa rede lenta, poderá ser mais rápido comparar somente as datas de modificação e os tamanhos dos arquivos. Porém, este melhoramento de velocidade traz alguma incerteza. Use esta opção com cuidado. Por padrão, está desligada.

Confiar no tamanho (inseguro)

- É semelhante à comparação da data de modificação. Não ocorre nenhuma comparação em si. Dois arquivos quaisquer são considerados iguais se os seus tamanhos de arquivos forem iguais. Isto é útil quando a operação de cópia de arquivos não preservar a data de modificação. Use esta opção com cuidado. Por padrão, está desligada.

Sincronizar pastas

- Ativa o modo de sincronização em que duas pastas são comparadas e não foi indicada nenhuma pasta de destino. Neste modo, as operações propostas serão escolhidas de modo a que ambas as pastas de origem fiquem iguais no fim. Do mesmo modo, o resultado da mesclagem será salvo em ambas as pastas. Por padrão, esta opção está desligada.

Copiar mais novo ao invés de mesclar (inseguro)

- Em vez de mesclar, a operação proposta irá copiar os arquivos mais recentes se ocorreram algumas alterações. (É considerado inseguro, porque implica saber se o outro arquivo não foi também alterado. Verifique para se certificar em qualquer um dos casos.). Por padrão, a opção está desligada.

Arquivos de backup (.orig)

- Se um arquivo ou uma pasta completa for substituído por outro ou for removido, então a versão original mudará para um nome com uma extensão `.orig`. Se já existir um arquivo antigo com uma extensão `.orig`, então este será removido sem ser criada nenhuma cópia de segurança. Isto também afeta a mesclagem normal de arquivos simples, não só no modo de mesclagem de pastas. Por padrão, a opção está ativa.

### Outras funções na janela de mesclagem de pastas

#### Modo de Tela Repartido/Completo

Normalmente a lista de mesclagem da pasta fica visível enquanto um único arquivo é comparado ou reunido. Com o mouse, o usuário poderá mover a barra separadora que delimita a lista de arquivos das janelas de diferenças do texto. Se você não a quiser, poderá desativar o item de menu Pasta Pasta && Vista da tela dividida do texto. Aí, poderá usar o item de menu Pasta Alternar vista para alternar entre a lista de arquivos e a janela de diferenças no texto que irá então ocupar toda a tela.

#### Comparar ou Mesclar um Único Arquivo

Provavelmente, você irá preferir um duplo-clique do mouse simples sobre um arquivo para poder compará-lo. Contudo, existe também um item no menu Pasta. Você poderá também mesclar diretamente um único arquivo sem iniciar a mesclagem de pastas, através do item de menu Mesclar Mesclar arquivo atual. Ao salvar o resultado, o estado ficará como terminado e o arquivo não será mesclado de novo se for iniciada uma mesclagem de pastas.

Mas repare que esta informação de estado será perdida quando voltar a executar uma pesquisa de pastas: Pasta Pesquisar de novo

#### Comparar ou Mesclar Arquivos com Nomes Diferentes

Em alguns casos, você terá que comparar ou mesclar arquivos com nomes diferentes (⪚, o arquivo atual e a cópia de segurança na mesma pasta).

Selecione o arquivo exato, clicando no ícone na coluna A, B ou C. O primeiro arquivo selecionado será então marcado com um A, enquanto o segundo e o terceiro ficará com um B e um C, independentemente da coluna em que se encontram. Você só poderá escolher até três arquivos desta forma.

Siga com a escolha de Pasta Comparar arquivos explicitamente selecionados ou Pasta Mesclar arquivos explicitamente selecionados. Por conveniência, estes itens de menu também aparecem como um menu de contexto, quando clicar com o botão direito no último arquivo selecionado.

A comparação ou mesclagem de um arquivo irá acontecer na mesma janela. Se este método for usado para as pastas, será aberta uma nova janela.

## Tópicos Diversos

### Transparência de rede através do KIO

#### KIO-Slaves

A biblioteca KIO do &frameworks; suporta a transparência de rede através dos 'KIO-slaves'. O &kdiff3; usa isto para ler os arquivos de entrada e para pesquisar as pastas. Isto significa que você poderá indicar arquivos e pastas em recursos locais e remotos através dos &URL;s.

Exemplo:

    kdiff3 teste.cpp  ftp://ftp.longe.org/teste.cpp
       kdiff3 tar:/home/eu/pacote.tar.gz/pasta ./pasta

A primeira linha compara um arquivo local com outro arquivo num servidor de &FTP;. A segunda linha compara uma pasta dentro de um pacote comprimido com uma pasta local.

Outros 'KIO-slaves' que serão interessantes:

- Arquivos da WWW (http:),

- Arquivos de &FTP; (ftp:),

- Transferência de arquivos criptografada (fish:, sftp:),

- Recursos do &Windows; (smb:),

- Arquivos locais (file:),

Outras coisas que são possíveis, mas provavelmente serão menos interessantes:

- Páginas do 'man' (man:),

- Páginas do 'info' (info:),

#### Como escrever &URL;s

Um &URL; tem uma sintaxe diferente, em comparação com as localizações dos arquivos e pastas locais. Alguns fatores terão que ser considerados:

- Uma localização poderá ser relativa e conter "." ou "..". Isto não é possível para os &URL;s, uma vez que eles são sempre absolutos.

- Caracteres especiais devem ser escritos com "escape". ("`#`" -> "`%23`", espaço ->"`%20`", &etc;) Por exemplo, um arquivo com o nome "`#`foo`#`" teria a &URL; "file:/`%23`foo`%23`".

- Quando os &URL;s não funcionarem como seria de esperar, tente abri-los primeiro no &konqueror;.

#### Capacidades dos 'KIO-Slaves'

A transparência de rede tem um senão: nem todos os recursos têm as mesmas capacidades.

Algumas das vezes isto é devido ao sistema de arquivos do servidor, enquanto que em outras ocasiões poderá ser devido ao protocolo. Aqui está uma pequena lista das restrições:

- Em alguns casos não existe o suporte para ligações simbólicas.

- Ou não existe forma de distinguir se uma ligação aponta para um arquivo ou uma pasta; é assumido sempre um arquivo. (ftp:, sftp:).

- Não é sempre possível determinar o tamanho do arquivo.

- Existe um suporte de permissões limitado.

- Não existe a possibilidade de modificar as permissões ou a data de modificação, assim as permissões ou a data de uma cópia poderão ser diferentes do original. (Veja a opção Confiar no tamanho (inseguro).) (A modificação de permissões ou das datas só é possível para os arquivos locais.)

### Usando o &kdiff3; como uma ferramenta de comparação e mesclagem do &git;

&kdiff3; pode ser usado como uma ferramenta de comparação e mesclagem do &git;

Basta adicionar as seguintes linhas ao seu arquivo `gitconfig`.

    [diff]
            tool = kdiff3
    [difftool "kdiff3"]
            path = <caminho para o binário do kdiff3 no seu sistema>
    [difftool]
            prompt = false
            keepBackup = false
            trustExitCode = false
    [merge]
            tool = kdiff3
    [mergetool]
            prompt = false
            keepBackup = false
            keepTemporaries = false
    [mergetool "kdiff3"]
            path = <caminho para o binário do kdiff3 no seu sistema
    >

Para ver a diferença entre dois commits, use `git difftool `primeiro_hash` `segundo_hash` --tool=kdiff3 --cc `algum_arquivo_na_árvore_git``

Para mesclar uma branch com o kdiff3, use `git merge `nome_da_branch` && git mergetool --tool=kdiff3`

Após resolver os conflitos de mesclagem da maneira usual, basta confirmar as alterações para que o trabalho seja concluído.

## Perguntas e respostas

&reporting.bugs; &updating.documentation;

Porque é que se chama "&kdiff3;"?

As ferramentas KDiff e KDiff2 (agora chamada &kompare;) já existiam. Além disso, o &kdiff3; deveria sugerir que consegue juntar arquivos como a ferramenta `diff`" da coleção de ferramentas do Diff.

Porque foi lançado segundo a GPL?

O autor usou programas GPL durante muito tempo até agora e aprendeu bastante ao olhar para muito código. Daí, este é o "Muito Obrigado" para todos os programadores que também o fizeram ou irão fazer no futuro.

Faltam alguns botões e funções. O que está errado?

Você compilou a partir do código mas não indicou provavelmente o prefixo correto para instalação. Por padrão, o `cmake` prefere insalar em `/usr/local`, mas então o arquivo de recursos da interface do usuário (&ie;, o `kdiff3ui.rc`). O arquivo `README` contém mais informações sobre o prefixo correto.

Muitas das vezes as linhas que são semelhantes mas não idênticas aparecem umas ao lado das outras mas noutros casos não. Porquê?

As linhas em que apenas a quantidade de espaços em branco é diferente são tratadas como "iguais" à primeira vista, embora apenas um caractere que não seja um espaço em branco faça com que as linhas sejam "diferentes". Se as linhas semelhantes aparecerem uma ao lado da outra, isto poderá ser de fato uma coincidência, mas é felizmente o caso mais frequente. Veja também em Ajuda das Diferenças Manuais.

Porque todos os conflitos deverão ser resolvidos para que o resultado da mesclagem possa ser salvo?

Para cada seção igual ou diferente, o editor na janela do resultado da mesclagem recorda onde ela começa ou termina. Isto é necessário para que os conflitos possam ser resolvidos manualmente ao selecionar simplesmente o botão da origem (A, B ou C). Esta informação é perdida durante a gravação como texto e corresponde a muito esforço criar um formato de arquivo especial que suporte o salvamento e a restauração de toda a informação necessária.

Como eu posso sincronizar as janelas de diferenças e mesclagem, de modo que todas mostrem a mesma posição de texto?

Clique na coluna de resumo à esquerda do texto. (Veja também aqui.)

Por que `git difftool --dir-diff` retorna o erro "Mix of links and normal files error" ao usar o KDiff3 como ferramenta de comparação?

Este é um efeito colateral do funcionamento interno do Git. Se você tentar comparar uma revisão anterior com a árvore de trabalho atual, o Git comparará, na verdade, arquivos que representam o commit anterior com links simbólicos que apontam para a árvore de trabalho. A partir da versão 1.9, o KDiff3 tem ativado por padrão as opções Seguir links de arquivos e Seguir links de pastas. Antes disso, elas estavam desativadas por padrão. Isso não importava se a opção "Análise completa" também estivesse desativada. No entanto, com a opção Análise completa ativada, o KDiff3 inicialmente tentaria comparar o caminho apontado por um link em vez de segui-lo. Antes da versão 1.8, o erro resultante era ignorado. No entanto, a versão 1.8 começou a reportar o erro.

Porque o editor na janela do resultado da mesclagem não tem uma função para "desfazer"?

Isso era muito difícil até agora. Você poderá sempre restaurar uma versão de uma origem (A, B ou C) se clicar no botão respectivo. Para uma edição extensa, recomenda-se a utilização de outro editor, de qualquer forma.

Quando eu removi algum texto, apareceu de repente "<Sem linha de origem>" e esta não pode ser removida. O que significa e como é possível removê-la?

Para cada seção igual ou diferente, o editor na janela do resultado da mesclagem recorda onde ela começa ou termina. O "<Sem linha de origem>" significa que não existe mais nada livre numa seção, nem mesmo um caractere de mudança de linha. Isto poderá acontecer durante a mesclagem automática ou durante a edição. Isto não é nenhum problema, uma vez que esta dica não irá aparecer no arquivo salvo. Se você quiser os dados originais de volta, basta selecionar a seção (clique na coluna de resumo à esquerda) e depois no botão da origem com o conteúdo necessário (A/B ou C).

Porque o &kdiff3; não suporta o realce de sintaxe?

O &kdiff3; já usa muitas cores para o realce das diferenças. Se suportasse o realce de sintaxe, tornar-se-ia confuso. Use outro editor para esse efeito.

Posso usar o &kdiff3; para comparar arquivos LibreOffice/OpenOffice.org, &Microsoft; Word, &Microsoft; Excel, &PDF;, &etc;?

Ainda que o &kdiff3; analise qualquer tipo de arquivo, o resultado poderá não ser muito satisfatório para você.

O &kdiff3; foi feito para comparar arquivos de texto puros. O LibreOffice/OpenOffice, &Microsoft; Word, &Microsoft; Excel, &etc; gravam muito mais informação nos arquivos (sobre os tipos de fonte, imagens, páginas, cores, &etc;), que o &kdiff3; não conhece. Deste modo, o &kdiff3; mostrará o conteúdo do arquivo interpretado como texto puro, mas ele poderá estar ilegível ou, pelo menos, ficará muito esquisito.

Uma vez que a maioria dos programas, nos dias de hoje, gravam o seu conteúdo no formato &XML;, você poderá ser capaz de lê-los como texto puro. Por isso, se a alteração foi pequena, o &kdiff3; ainda poderá ajudá-lo.

A melhor solução, se quiser apenas comparar o texto (sem as imagens incorporadas, como as imagens), é usar o Editar Selecionar tudo e o Editar Copiar no seu programa, para copiar o texto interessante para a área de transferência e depois, no &kdiff3;, colar o texto em qualquer uma das janelas de entrada. (Veja também o Selecionar, Copiar e Colar.)

Para onde foi a opção de pastas Listar apenas os deltas?

Existem agora várias opções "Mostrar" no menu Pastas. Se desativar o Mostrar arquivos iguais, irá obter o mesmo resultado do Listar apenas os deltas.

Como eu faço uma grande seleção na janela de entrada de diferenças, uma vez que o deslocamento leva tanto tempo?

Comece a seleção da forma normal (clique e mantenha o &LMB; pressionado). Depois, use as teclas de navegação (⪚, o &PgUp;, &PgDn;), enquanto mantém pressionado o &LMB;. (Veja também em Selecionar, Copiar e Colar.)

Existe muita informação aqui, mas a sua dúvida ainda não foi respondida?

Por favor envie ao autor a sua dúvida. Ele agradece qualquer comentário.

## Créditos e licença

&kdiff3; - Ferramenta de comparação e mesclagem de arquivos e pastas

Direitos autorais do programa 2002-2007 Joachim Eibl joachim.eibl at gmx.de

Vieram várias ideias legais e relatórios de erros dos colegas do autor e de pessoas da Wild Wild Web. Muito obrigado!

Direitos autorais da documentação © 2002-2007 Joachim Eibl joachim.eibl at gmx.de

Direitos autorais da documentação © 2017-2019 Michael Reeves reeves.87 at gmail.com

Tradução de Marcus Gama marcus.gama@gmail.com

&underFDL; &underGPL;
&documentation.index;