Submodules, subtrees ou vendoring: três formas de incluir outro repositório

O que é

Existem três mecanismos para trazer o código de outro repositório para o seu:

• Submodule. A árvore do superprojeto contém uma entrada gitlink com o ID do commit em que o submodule deve estar, e o .gitmodules registra o caminho e a URL. O submodule mantém o próprio histórico e o próprio diretório Git. A documentação afirma que, depois de git submodule update, o commit registrado é obtido por checkout em um HEAD desanexado (detached HEAD).
• Subtree. git subtree add --prefix=<dir> <repository> <ref> importa os arquivos do outro projeto para um subdiretório como arquivos rastreados comuns; com --squash, importa-se apenas um único commit em vez de todo o histórico. git subtree pull e git subtree push levam as alterações nos dois sentidos. O manual destaca que subtrees não exigem construções especiais, como .gitmodules ou gitlinks, e não obrigam os usuários finais a fazer nada.
• Vendoring. Copie os arquivos, faça o commit e escreva a versão do upstream, a URL de origem e eventuais patches locais em um arquivo ao lado deles (VENDOR.md ou um lock file).

Por que importa

A escolha determina como fica um clone novo, como se faz uma atualização e se é possível fazer modificações locais. Submodules são exatos, mas exigem git clone --recurse-submodules ou git submodule update --init --recursive de todos, inclusive do CI; esquecer isso resulta em diretórios vazios. Subtrees e vendoring produzem um clone autossuficiente, ao custo de um histórico maior e de uma procedência menos evidente.

Como aplicar

• Prefira um gerenciador de pacotes quando houver um para a linguagem; essas três opções servem para os casos em que nenhum se encaixa (configuração compartilhada, assets, um fork privado).
• Use submodules quando a dependência for grande, mudar de forma independente e precisar ser fixada em um commit exato no qual você também desenvolve.
• Use subtrees quando os consumidores não precisarem saber da existência dela e as atualizações forem ocasionais (git subtree pull --squash mantém o histórico curto).
• Faça vendoring quando a dependência for pequena e estável; anote a versão e a licença para que a cópia possa ser auditada e atualizada.
• Seja qual for a escolha, coloque o comando de atualização no README e execute o build a partir de um clone novo no CI.

Armadilhas

Commits de submodule enviados ao superprojeto, mas não ao remoto do submodule, quebram todos os outros clones. Commits feitos dentro de um submodule em HEAD desanexado não pertencem a nenhum branch e são fáceis de perder, a menos que um branch seja criado antes. O manual do subtree pede consistência com --squash: se todos os merges forem feitos com squash, o split --rejoin também deve ser; caso contrário, o log mostra uma cópia de cada commit. Cópias de vendoring divergem silenciosamente quando alguém as altera sem atualizar o registro.