Close

Submódulos do Git

Os submódulos do Git permitem que você mantenha um repositório do Git como um subdiretório de outro repositório do Git. Os submódulos do Git são uma referência a outro repositório em um instantâneo específico no tempo. Os submódulos do Git permitem que um Repositório do Git incorpore e rastreie o histórico de versões de código externo.


O que é um submódulo git?


Muitas vezes, um repositório de código depende de código externo. Esse código externo pode ser incorporado de algumas maneiras diferentes. O código externo pode ser copiado e colado direto no repositório principal. Esse método tem a desvantagem de perder quaisquer alterações upstream no repositório externo. Outro método de incorporação de código externo é por meio do uso do sistema de gerenciamento de pacotes de uma linguagem, como Ruby Gems ou NPM. Esse método tem a desvantagem de exigir instalação e gerenciamento de versão em todos os lugares em que o código de origem é implantado. Ambos os métodos de incorporação sugeridos não permitem o rastreamento de edições e alterações no repositório externo.

Um submódulo git é um registro dentro de um repositório do Git host que aponta para um commit específico em outro repositório externo. Os submódulos são muito estáticos e rastreiam apenas commits específicos. Os submódulos não rastreiam git refs ou ramificações e não são atualizados quando o repositório do host é atualizado. Ao adicionar um submódulo a um repositório, um novo arquivo .gitmodules será criado. O arquivo .gitmodules contém metadados sobre o mapeamento entre a URL do projeto do submódulo e o diretório local. Se o repositório do host tiver vários submódulos, o arquivo .gitmodules terá uma entrada para cada submódulo.

Quando você deve usar um submódulo git?


Se você precisar manter um gerenciamento de versão rigoroso sobre as dependências externas, pode fazer sentido usar submódulos git. A seguir estão alguns dos melhores casos de uso para submódulos git.

  • Quando um componente ou subprojeto está mudando muito rápido ou as próximas mudanças vão quebrar a API, você pode bloquear o código para um commit específico para sua própria segurança.
  • Quando você tem um componente que não é atualizado com muita frequência e quer rastrear este componente como uma dependência do fornecedor.
  • Quando você está delegando uma parte do projeto a um terceiro e quer integrar o trabalho deles em um horário ou versão específico. De novo: funciona quando as atualizações não são muito frequentes.
bancos de dados
Material relacionado

Como mover um Repositório do Git completo

Logotipo do Bitbucket
VER SOLUÇÃO

Aprenda a usar o Git com o Bitbucket Cloud

Comandos comuns para submódulos git


Submódulo git add

O submódulo git add é usado para adicionar um novo submódulo a um repositório existente. Veja a seguir um exemplo que cria um repositório vazio e explora os submódulos git.

$ mkdir git-submodule-demo
$ cd git-submodule-demo/
$ git init
Initialized empty Git repository in /Users/atlassian/git-submodule-demo/.git/

Essa sequência de comandos vai criar um novo diretório git-submodule-demo, entrar nesse diretório e iniciar como um novo repositório. Em seguida, vamos adicionar um submódulo a esse novo repositório.

$ git submodule add https://bitbucket.org/jaredw/awesomelibrary
Cloning into '/Users/atlassian/git-submodule-demo/awesomelibrary'...
remote: Counting objects: 8, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 8 (delta 1), reused 0 (delta 0)
Unpacking objects: 100% (8/8), done.

O comando git submodule add usa um parâmetro de URL que aponta para um repositório do Git. Aqui nós adicionamos a awesomelibrary como um submódulo. O Git vai clonar de imediato o submódulo. Agora podemos revisar o estado atual do repositório usando git status...

$ git status
On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

new file:   .gitmodules
new file:   awesomelibrary

Agora existem dois novos arquivos no repositório .gitmodules e o diretório awesomelibrary. Olhando para o conteúdo de .gitmodules mostra o novo mapeamento do submódulo

[submodule "awesomelibrary"]
path = awesomelibrary
url = https://bitbucket.org/jaredw/awesomelibrary
$ git add .gitmodules awesomelibrary/
$ git commit -m "added submodule"
[main (root-commit) d5002d0] added submodule
 2 files changed, 4 insertions(+)
 create mode 100644 .gitmodules
 create mode 160000 awesomelibrary

Clonando submódulos git

git clone /url/to/repo/with/submodules
git submodule init
git submodule update

Git submodule Init

O comportamento padrão do submódulo git init é copiar o mapeamento do arquivo .gitmodules no arquivo ./.git/config local. Isso pode parecer redundante e levar a questionar a utilidade do git submodule init. git submodule init tem um comportamento de extensão no qual aceita uma lista de nomes de módulos explícitos. Isso permite que um fluxo de trabalho ative apenas submódulos específicos que são necessários para o trabalho no repositório. Isso pode ser útil se houver muitos submódulos em um repositório, mas nem todos precisarem ser buscados para o trabalho que você está fazendo.

Fluxos de trabalho do submódulo

Depois que os submódulos são inicializados e atualizados dentro de um repositório pai, eles podem ser utilizados como repositórios independentes. Isso significa que os submódulos têm suas próprias ramificações e histórico. Ao fazer alterações em um submódulo, é importante publicar as alterações do submódulo e, em seguida, atualizar a referência do repositório pai para o submódulo. Vamos continuar com o exemplo da awesomelibrary e fazer algumas mudanças:

$ cd awesomelibrary/
$ git checkout -b new_awesome
Switched to a new branch 'new_awesome'
$ echo "new awesome file" > new_awesome.txt
$ git status
On branch new_awesome
Untracked files:
  (use "git add <file>..." to include in what will be committed)

new_awesome.txt

nothing added to commit but untracked files present (use "git add" to track)
$ git add new_awesome.txt
$ git commit -m "added new awesome textfile"
[new_awesome 0567ce8] added new awesome textfile
 1 file changed, 1 insertion(+)
 create mode 100644 new_awesome.txt
$ git branch
  main
* new_awesome

Aqui, mudamos o diretório para o submódulo awesomelibrary. Criamos um novo arquivo de texto new_awesome.txt com algum conteúdo e adicionamos e fizemos commit desse novo arquivo ao submódulo. Agora, vamos alterar os diretórios de volta para o repositório pai e revisar o estado atual do repositório pai.

$ cd ..
$ git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

modified:   awesomelibrary (new commits)

no changes added to commit (use "git add" and/or "git commit -a")

A execução de git status nos mostra que o repositório pai está ciente dos novos commits para o submódulo awesomelibrary. Ele não entra em detalhes sobre as atualizações específicas porque essa é a responsabilidade dos repositórios do submódulo. O repositório pai só se preocupa em fixar o submódulo em um commit. Agora podemos atualizar o repositório pai novamente fazendo um git add e git commit no submódulo. Isso colocará tudo em um bom estado com o conteúdo local. Se você estiver trabalhando em um ambiente de equipe, é fundamental que você faça o git push das atualizações do submódulo e as atualizações do repositório pai.

Ao trabalhar com submódulos, um padrão comum de confusão e erro é esquecer de enviar atualizações para usuários remotos. Se revisitarmos o trabalho com awesomelibrary que acabamos de fazer, enviaremos apenas as atualizações para o repositório pai. Outro desenvolvedor iria enviar pull para o repositório pai mais recente e estaria apontando para um commit da awesomelibrary que eles não conseguiram enviar pull porque tínhamos esquecido de enviar push do submódulo. Isso quebraria o repositório local dos desenvolvedores remotos. Para evitar esse cenário de falha, sempre faça commit e envie push do submódulo e do repositório pai.

Conclusão


Os submódulos do Git são uma maneira poderosa de aproveitar o git como uma ferramenta externa de gerenciamento de dependências. Avalie os prós e os contras dos submódulos git antes de usá-los, pois eles são uma função avançada e podem exigir uma curva de aprendizado para os membros da equipe adotarem.


Compartilhar este artigo

Leitura recomendada

Marque esses recursos para aprender sobre os tipos de equipes de DevOps ou para obter atualizações contínuas sobre DevOps na Atlassian.

Pessoas colaborando usando uma parede cheia de ferramentas

Blog do Bitbucket

Ilustração do DevOps

Caminho de aprendizagem de DevOps

Demonstrações de funções no Demo Den com parceiros da Atlassian

Como o Bitbucket Cloud funciona com o Atlassian Open DevOps

Inscreva-se para receber a newsletter de DevOps

Thank you for signing up