Combina Arquivos

Extensão para VS Code que combina vários arquivos selecionados no Explorer em um único arquivo, com todo o comportamento controlado por um arquivo de configuração global — único por usuário, válido em qualquer projeto, com autocomplete e validação ao editar.

O resultado é aberto em uma aba não salva — basta pressionar Ctrl+S para salvar onde você quiser.

Sumário

• Início rápido
• Como usar
• Referência rápida
• Onde configurar
• Configuração
  • Propriedades globais
  • Codificação
  • Grupos de configuração
  • Remoção de conteúdo
  • Variáveis de entrada
  • Saída
• Exemplos completos
  • Exemplo genérico
  • Exemplo com grupo
• Variáveis disponíveis
• Ordem de processamento
• Fluxo de execução
• Tratamento de erros
• Configurações da extensão (VS Code)

Início rápido

1. Abra a paleta de comandos (Ctrl+Shift+P) e execute Combina Arquivos: Abrir configuração global. Na primeira vez, um arquivo já preenchido é criado e aberto. Ajuste o que quiser e salve — vale em todos os projetos.
2. No Explorer, selecione dois ou mais arquivos (use Ctrl/Shift para multiseleção).
3. Clique com o botão direito e escolha Combinar arquivos.
4. Preencha as variáveis solicitadas (se houver).
5. O resultado abre em uma aba não salva. Salve com Ctrl+S.

Funciona sem configurar nada: sem arquivo de configuração, os padrões internos já combinam os arquivos com uma linha em branco entre eles.

Como usar

A extensão adiciona um item Combinar arquivos ao menu de contexto do Explorer. Você pode selecionar arquivos ou pastas (pastas são percorridas recursivamente).

Toda a lógica de combinação — cabeçalhos, rodapés, separadores, remoções, ordem e codificação — vem do arquivo de configuração (global ou override de projeto).

Referência rápida

Propriedades globais (e que cada grupo pode sobrescrever)

• encoding — string (padrão "utf8"). Codificação para ler os arquivos e gravar a saída. Aceita qualquer valor do iconv-lite: utf8, utf16le, windows-1252, cp1252, iso-8859-1, windows-1250, cp850…
• order — string (padrão "selection"). Ordem em que os arquivos são combinados. Valores: selection, name-asc, name-desc, path-asc, path-desc, extension, mtime-asc, mtime-desc, size-asc, size-desc.
• separator — string (padrão "\n\n"). Conteúdo inserido entre um arquivo e outro.
• header — string[] (padrão []). Linhas inseridas uma vez no início do resultado (unidas por \n; "" = linha em branco).
• footer — string[] (padrão []). Linhas inseridas uma vez no fim do resultado.
• fileHeader — string[] (padrão []). Linhas inseridas antes do conteúdo de cada arquivo.
• fileFooter — string[] (padrão []). Linhas inseridas depois do conteúdo de cada arquivo.
• removals — objeto[] (padrão []). Regras de remoção aplicadas a cada arquivo, na ordem declarada.
• variables — objeto[] (padrão []). Variáveis pedidas ao usuário no início (também válidas dentro de grupos).
• output — objeto (padrão { "mode": "untitled" }). Configuração de saída.
• groups — objeto[] (padrão []). Grupos específicos por padrão de caminho, aplicados em cascata.

Item de removals

• type — "literal" | "regex". Tipo da remoção. Obrigatório.
• value — string. Texto exato a remover (quando type = literal).
• pattern — string. Expressão regular (quando type = regex).
• flags — string (padrão "g"). Flags da regex (ex.: gi, gm).

Item de variables

• name — string. Nome usado na substituição, ex.: ${autor}. Obrigatório.
• prompt — string. Texto exibido na caixa de entrada.
• description — string. Texto auxiliar (placeholder).
• default — string. Valor padrão pré-preenchido.
• required — boolean (padrão false). Aborta se o valor ficar vazio.
• password — boolean (padrão false). Esconde o valor digitado.
• options — string[]. Exibe um seletor de opções em vez de texto livre.

Objeto output

• mode — "untitled" | "file" | "ask" (padrão "untitled"). untitled abre aba não salva (Ctrl+S); file grava direto; ask pergunta o local.
• path — string. Caminho de saída (modos file/ask); relativo ao workspace ou absoluto. Suporta variáveis.
• fileName — string. Nome sugerido do arquivo. Suporta variáveis.
• language — string. Linguagem da aba para realce de sintaxe (ex.: sql, markdown, typescript).

Item de groups

• name — string. Nome do grupo (usado em mensagens). Obrigatório.
• patterns — string[]. Padrões glob de caminho que ativam o grupo (**, *, ?). Obrigatório.
• priority — number (padrão 0). Quanto maior, mais específico (aplicado por último na cascata, vence).
• + qualquer propriedade global — encoding, order, separator, header, footer, fileHeader, fileFooter, removals, output, variables. Sobrescrevem o que definirem; o resto é herdado.

Setting do VS Code

• combinaArquivos.configPath — string (padrão ""). Opcional. Caminho de um arquivo .jsonc/.json que sobrescreve a config global só naquele projeto. Vazio = usar a configuração global.

Onde configurar

1. Configuração global (recomendado). Comando Combina Arquivos: Abrir configuração global. É um arquivo .jsonc único, guardado na área global da extensão (globalStorage), que vale em qualquer pasta/projeto.

   • Aceita comentários (JSONC) e tem autocomplete + validação ao editar (via JSON Schema).
   • Como é um arquivo seu, dá para versionar/fazer backup à parte.

2. Override por projeto (opcional). Comando Combina Arquivos: Criar configuração de projeto (override) gera um .combina-arquivos.jsonc na raiz do workspace (a partir da config atual) e oferece ativá-lo automaticamente em combinaArquivos.configPath. Quando ativo, ele sobrescreve a global apenas naquele projeto.

Precedência: override de projeto (configPath) ➜ arquivo global ➜ padrões internos. O primeiro que existir é usado.

Configuração

O arquivo (global ou de projeto) é JSONC (aceita comentários). Estrutura geral:

{
  // Propriedades globais (usadas quando nenhum grupo corresponde)
  "encoding": "utf8",
  "order": "name-asc",
  "separator": "\n\n",
  "header": ["// Projeto: ${workspaceName} — ${datetime}", ""],
  "footer": ["", "// Fim — ${total} arquivo(s)."],
  "fileHeader": ["// ===== ${relativePath} (${index}/${total}) =====", ""],
  "fileFooter": [],
  "removals": [],
  "variables": [],
  "output": { "mode": "untitled" },
  "groups": []
}

Cabeçalhos e rodapés são listas de strings. Cada item da lista é uma linha; os itens são unidos por \n. Para inserir uma linha em branco, adicione "". Uma lista vazia ([]) não insere nada.

Propriedades globais

Todas as propriedades de texto suportam variáveis.

Codificação

A codificação pode ser definida globalmente (encoding) ou por grupo (a do grupo sobrescreve a global). São aceitas todas as codificações reconhecidas pelo iconv-lite, incluindo Windows-1252.

Exemplos de valores válidos:

Para salvar em Windows-1252:

{
  "encoding": "windows-1252",
  "output": { "mode": "file", "path": "dist", "fileName": "saida.txt" }
}

⚠️ Importante sobre o modo untitled. A encoding é sempre usada para ler os arquivos de entrada. Para gravar no encoding escolhido, use output.mode igual a file ou ask — aí a extensão grava os bytes diretamente em Windows-1252. No modo untitled (aba não salva), o editor mantém o texto em UTF-8 até você salvar; ao pressionar Ctrl+S o VS Code salva em UTF-8 por padrão. Para salvar a aba em Windows-1252, use "Salvar com codificação" (paleta de comandos → Save with Encoding → Western (Windows 1252)) ou prefira mode: "file".

Grupos de configuração

Grupos permitem comportamentos diferentes por caminho. Cada grupo tem um name, uma lista de patterns (glob) e, opcionalmente, qualquer propriedade global para sobrescrever.

"groups": [
  {
    "name": "TypeScript",
    "patterns": ["**/*.ts", "**/*.tsx"],
    "priority": 10,
    "output": { "language": "typescript" },
    "fileHeader": ["// --- ${fileName} ---", ""]
  }
]

Regras de seleção (herança em cascata):

• Um grupo é considerado apenas quando todos os arquivos selecionados correspondem a pelo menos um de seus patterns.
• Todos os grupos compatíveis são aplicados em cascata, do menor para o maior priority (padrão 0). Cada propriedade usa o valor do grupo mais específico (maior priority) que a define; o que ele não define é herdado dos grupos de prioridade menor e, por fim, das propriedades globais do topo.
• Em empate de priority, vale a ordem de declaração (o declarado depois vence).
• output é mesclado em profundidade (campo a campo); as listas (header, footer, removals, etc.) são substituídas inteiras pelo grupo mais específico que as define.
• Se nenhum grupo corresponder, usam-se as propriedades globais.

Os patterns aceitam glob: ** (vários segmentos), * (um segmento) e ? (um caractere). Os caminhos comparados são relativos à raiz do workspace.

Exemplo de herança: um "SQL Global" + grupos específicos

"groups": [
  {
    // Base comum a TODO arquivo .sql (menor priority).
    "name": "SQL Global",
    "patterns": ["**/*.sql"],
    "priority": 10,
    "encoding": "windows-1252",
    "order": "name-asc",
    "separator": "\n",
    "removals": [
      { "type": "regex", "pattern": "USE\\s*\\[AB_EFINANCEIRA\\]\\s*GO" }
    ],
    "header": ["USE AB_EFINANCEIRA", ""],
    "fileHeader": ["/* ${fileName} (${index}/${total}) */"],
    "fileFooter": ["GO"],
    "output": { "mode": "file", "path": "unificados", "language": "sql" }
  },
  {
    // Específico: herda tudo do SQL Global e só ajusta o necessário.
    "name": "Procedures SQL",
    "patterns": ["**/PROCEDURES/**/*.sql", "**/PROC/**/*.sql"],
    "priority": 30,
    // Pede ${versao} apenas quando você combina procedures.
    "variables": [{ "name": "versao", "prompt": "Versão do script?", "required": true }],
    "footer": ["", "INSERT INTO VERSAO_SISTEMA (...) VALUES ('RN', '${versao}', ...)", "GO"],
    "output": { "fileName": "procedure-${date}.sql" }
  },
  {
    "name": "Tabelas SQL",
    "patterns": ["**/Tabelas/**/*.sql", "**/TAB/**/*.sql"],
    "priority": 12,
    "footer": ["", "INSERT INTO VERSAO_SISTEMA (...) VALUES (...)", "GO"],
    "output": { "fileName": "tabelas-${date}.sql" }
  }
]

Ao combinar arquivos em PROCEDURES/, a cascata é SQL Global → Procedures SQL. O resultado herda encoding, order, separator, removals, header, fileHeader, fileFooter do SQL Global, e do Procedures SQL vêm o footer e o output.fileName — com output mesclado, virando { mode: "file", path: "unificados", language: "sql", fileName: "procedure-${date}.sql" }.

Remoção de conteúdo

Aplicadas a cada arquivo, na ordem declarada, antes da montagem do resultado.

"removals": [
  { "type": "literal", "value": "// TODO" },
  { "type": "regex", "pattern": "console\\.log\\(.*\\);?", "flags": "g" }
]

• literal — remove todas as ocorrências do texto exato (value).
• regex — remove conforme a expressão regular (pattern + flags, padrão g).

Variáveis de entrada

Solicitadas ao usuário no início da execução. Os valores ficam disponíveis em qualquer campo que suporte substituição.

"variables": [
  { "name": "autor", "prompt": "Nome do autor?", "required": true },
  { "name": "versao", "default": "1.0.0" },
  { "name": "ambiente", "options": ["dev", "prod"] }
]

Variáveis também funcionam dentro de grupos. Declare variables no topo e/ou em qualquer grupo. As variáveis do global e de todos os grupos aplicáveis são reunidas e solicitadas uma única vez (sem duplicar por name). Se o mesmo name aparecer em mais de um lugar, vale a definição do grupo mais específico (maior priority). Assim, por exemplo, um grupo "Procedures SQL" pode pedir ${versao} só quando você combina procedures.

Saída

"output": {
  "mode": "untitled",      // "untitled" (padrão) | "file" | "ask"
  "path": "dist",          // usado em "file"/"ask"; relativo ao workspace ou absoluto
  "fileName": "combinado-${date}.txt",
  "language": "markdown"   // linguagem da aba (realce de sintaxe)
}

• untitled (padrão) — abre uma aba não salva. Salve com Ctrl+S onde quiser.
• file — grava diretamente no caminho resolvido (path + fileName).
• ask — abre o diálogo "Salvar como" no momento da execução.

Exemplos completos

Exemplo genérico

Configuração mínima e direta, sem grupos. Combina qualquer seleção, ordena por nome, adiciona um cabeçalho e identifica cada arquivo. O resultado abre em uma aba não salva.

{
  "encoding": "utf8",
  "order": "name-asc",
  "separator": "\n\n",
  "header": [
    "/* ==================================================",
    " * Projeto : ${workspaceName}",
    " * Gerado  : ${datetime}",
    " * Autor   : ${autor}",
    " * Arquivos: ${total}",
    " * ================================================== */",
    ""
  ],
  "footer": [
    "",
    "/* Fim do arquivo combinado — ${total} arquivo(s). */"
  ],
  "fileHeader": [
    "// ----- INÍCIO: ${relativePath} (${index}/${total}) -----",
    ""
  ],
  "fileFooter": [
    "",
    "// ----- FIM: ${fileName} -----"
  ],
  "removals": [
    { "type": "regex", "pattern": "^\\s*//\\s*TODO.*$", "flags": "gm" }
  ],
  "variables": [
    { "name": "autor", "prompt": "Nome do autor?", "required": true }
  ],
  "output": {
    "mode": "untitled",
    "language": "plaintext"
  }
}

Exemplo com grupo

Configuração com grupos: arquivos .ts/.tsx recebem realce TypeScript e um cabeçalho próprio; arquivos .md da pasta docs/ são gravados diretamente em disco. Qualquer outra seleção cai nas propriedades globais.

{
  // ----- Propriedades globais (fallback) -----
  "encoding": "utf8",
  "order": "path-asc",
  "separator": "\n\n",
  "header": ["// ${workspaceName} — combinado em ${date}", ""],
  "fileHeader": ["// >>> ${relativePath}", ""],
  "variables": [
    { "name": "autor", "prompt": "Autor?", "default": "Equipe" }
  ],
  "output": { "mode": "untitled" },

  // ----- Grupos específicos -----
  "groups": [
    {
      "name": "TypeScript",
      "patterns": ["**/*.ts", "**/*.tsx"],
      "priority": 20,
      "encoding": "utf8",
      "output": { "language": "typescript" },
      "header": [
        "/* Fontes TypeScript de ${workspaceName} */",
        "/* Autor: ${autor} — ${datetime} */",
        ""
      ],
      "fileHeader": [
        "// ===== ${fileName} (${index}/${total}) =====",
        ""
      ],
      "removals": [
        { "type": "regex", "pattern": "console\\.log\\(.*\\);?", "flags": "g" }
      ]
    },
    {
      "name": "Documentação",
      "patterns": ["docs/**/*.md", "**/README.md"],
      "priority": 10,
      "separator": "\n\n---\n\n",
      "header": ["# Documentação combinada — ${workspaceName}", ""],
      "fileHeader": ["## ${fileBaseName}", ""],
      "output": {
        "mode": "file",
        "path": "dist",
        "fileName": "docs-${date}.md",
        "language": "markdown"
      }
    }
  ]
}

Lembre-se das regras de seleção de grupo: todos os arquivos da seleção precisam casar com os patterns do grupo. Todos os grupos compatíveis são aplicados em cascata (menor → maior priority). Selecionar arquivos .ts e .md juntos cai nas propriedades globais, pois nenhum grupo cobre os dois tipos ao mesmo tempo.

Variáveis disponíveis

Use a sintaxe ${nome}. Tokens desconhecidos são mantidos literalmente.

Globais (em qualquer campo):

Por arquivo (apenas em fileHeader e fileFooter):

Ordem de processamento

Defina em order:

Fluxo de execução

1. Identifica os arquivos selecionados (pastas são expandidas).
2. Carrega a configuração (Settings do VS Code + override por arquivo, se houver).
3. Determina o grupo aplicável (ou usa o global).
4. Aplica as sobrescritas do grupo sobre as propriedades globais.
5. Solicita os valores das variáveis de entrada.
6. Ordena e processa os arquivos (decodifica, aplica remoções).
7. Aplica cabeçalhos, rodapés e separadores.
8. Monta o conteúdo final.
9. Entrega conforme output.mode (aba não salva por padrão).

Tratamento de erros

A configuração é validada antes da execução. A extensão exibe mensagens claras para:

• Erros de sintaxe no JSON (no arquivo de override).
• configPath apontando para um arquivo inexistente.
• Variáveis obrigatórias não preenchidas.
• Codificações inválidas.
• Expressões regulares ou regras de remoção mal formadas.
• Grupos sem name ou sem patterns.

Diante de um erro crítico, a execução não continua.

Configurações da extensão (VS Code)

A configuração em si fica no arquivo global (ou no override de projeto). A única setting do VS Code é o caminho do override:

Comandos