Como verificar o status dos submódulos Git em um repositório

GitBeginner
Pratique Agora

Introdução

Os submódulos Git (Git submodules) são um recurso poderoso que permite incluir repositórios externos dentro dos seus próprios projetos. Essa capacidade é particularmente útil quando seu projeto depende de bibliotecas ou componentes externos que são mantidos separadamente. Ao usar submódulos, você pode manter essas dependências atualizadas e bem gerenciadas.

Neste tutorial, você aprenderá como verificar o status dos submódulos Git em seu repositório, entender quais alterações foram feitas neles e garantir que estejam devidamente sincronizados com seus repositórios de origem.

Este é um Lab Guiado, que fornece instruções passo a passo para ajudá-lo a aprender e praticar. Siga as instruções cuidadosamente para completar cada etapa e ganhar experiência prática. Dados históricos mostram que este é um laboratório de nível iniciante com uma taxa de conclusão de 82%. Recebeu uma taxa de avaliações positivas de 96% dos estudantes.

Criando um Repositório com Submódulos

Vamos começar criando um repositório de exemplo com um submódulo para ter um ambiente prático para nosso aprendizado.

Configurando o Repositório Principal

Primeiro, criaremos um novo repositório principal onde adicionaremos nosso submódulo. Abra seu terminal e execute os seguintes comandos:

cd ~/project
mkdir main-repo
cd main-repo
git init

Você deve ver uma saída semelhante a:

Initialized empty Git repository in /home/labex/project/main-repo/.git/

Agora, vamos criar um arquivo simples em nosso repositório principal:

echo "## Main Repository" > README.md
git add README.md
git commit -m "Initial commit"

A saída deve indicar que você criou seu primeiro commit:

[master (root-commit) xxxxxxx] Initial commit
 1 file changed, 1 insertion(+)
 create mode 100644 README.md

Adicionando um Submódulo

Agora, vamos adicionar um submódulo ao nosso repositório principal. Para este tutorial, usaremos um pequeno repositório público como nosso submódulo:

git submodule add https://github.com/libgit2/libgit2-backends.git libs/libgit2-backends

Este comando clonará o repositório e o adicionará como um submódulo no diretório libs/libgit2-backends. Você deve ver uma saída semelhante a:

Cloning into '/home/labex/project/main-repo/libs/libgit2-backends'...
remote: Enumerating objects: xxx, done.
remote: Counting objects: 100% (xxx/xxx), done.
remote: Compressing objects: 100% (xxx/xxx), done.
remote: Total xxx (delta xx), reused xxx (delta xx), pack-reused xxx
Receiving objects: 100% (xxx/xxx), xxx KiB | xxx KiB/s, done.
Resolving deltas: 100% (xxx/xxx), done.

Entendendo as Mudanças

Quando você adiciona um submódulo, o Git cria um arquivo .gitmodules em seu repositório que rastreia a URL e o caminho do submódulo. Vamos dar uma olhada neste arquivo:

cat .gitmodules

Você deve ver um conteúdo semelhante a:

[submodule "libs/libgit2-backends"]
	path = libs/libgit2-backends
	url = https://github.com/libgit2/libgit2-backends.git

Vamos também verificar o status do nosso repositório:

git status

Você deve ver uma saída indicando que tanto o novo arquivo .gitmodules quanto o diretório do submódulo foram adicionados:

On branch master
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   .gitmodules
        new file:   libs/libgit2-backends

Vamos commitar essas mudanças para completar nossa configuração:

git commit -m "Add libgit2-backends submodule"

Você agora deve ter um repositório com um submódulo configurado com sucesso.

Verificando o Status dos Submódulos

Agora que temos um repositório com um submódulo, vamos aprender como verificar o status do submódulo e entender o que a saída significa.

Verificação Básica do Status do Submódulo

O Git fornece um comando específico para verificar o status dos submódulos. Execute o seguinte comando:

cd ~/project/main-repo
git submodule status

Você deve ver uma saída semelhante a:

+abcdef1234567890abcdef1234567890abcdef12 libs/libgit2-backends (v1.0.0-123-gabcdef12)

Vamos entender o que essa saída significa:

  1. O primeiro caractere pode ser um dos seguintes:

    • +: indica que o commit do submódulo verificado difere do que está registrado no repositório principal
    • (espaço): indica que o submódulo está sincronizado com o que está registrado
    • -: indica que o submódulo não está inicializado
    • U: indica conflitos de merge no submódulo
  2. A string alfanumérica é o hash do commit do commit atual verificado no submódulo.

  3. O caminho mostra onde o submódulo está localizado em seu repositório.

  4. O texto entre parênteses mostra informações adicionais sobre o commit verificado, como tags ou nomes de branch.

Informações Detalhadas do Submódulo

Para obter informações mais detalhadas sobre seus submódulos, você pode usar o seguinte comando:

git submodule

Isso mostrará informações semelhantes ao comando status, mas em um formato diferente.

Usando Git Status para Ver Mudanças no Submódulo

Você também pode usar o comando git status padrão para ver as mudanças nos submódulos:

git status

Se não houver alterações no submódulo, você não verá nenhuma menção a ele na saída. No entanto, se houver alterações no commit verificado do submódulo ou nos arquivos dentro do submódulo, git status mostrará essas informações.

Examinando o Conteúdo do Submódulo

Vamos examinar o conteúdo do nosso submódulo:

cd ~/project/main-repo
ls -la libs/libgit2-backends/

Você verá os arquivos do repositório libgit2-backends. Observe que o submódulo é essencialmente um repositório Git completo dentro do seu repositório principal. Você pode verificar isso verificando a presença de um diretório .git:

ls -la libs/libgit2-backends/.git

Você pode não ver um diretório .git diretamente, mas sim um arquivo que aponta para os dados reais do repositório Git armazenados no diretório .git/modules do seu repositório principal. É assim que o Git gerencia os submódulos.

Entendendo a Referência do Submódulo

O repositório principal armazena uma referência a um commit específico no repositório do submódulo. Essa referência é o que o Git usa para saber qual versão do submódulo deve ser verificada ao clonar seu repositório ou atualizar o submódulo.

Vamos ver o commit que nosso repositório principal está referenciando:

cd ~/project/main-repo
git ls-files --stage libs/libgit2-backends

A saída mostrará um hash de commit, que é o commit específico do submódulo que o repositório principal está rastreando.

Atualizando Submódulos

Uma tarefa comum ao trabalhar com submódulos é mantê-los atualizados com seus repositórios remotos. Vamos aprender como atualizar nosso submódulo.

Inicializando e Atualizando Submódulos

Se você acabou de clonar um repositório que contém submódulos, precisará inicializá-los e atualizá-los. Para nosso repositório existente, podemos demonstrar este processo com:

cd ~/project/main-repo
git submodule init
git submodule update

O comando init inicializa a configuração dos seus submódulos, e o comando update busca os dados e verifica o commit especificado em seu repositório principal.

Você também pode combinar esses comandos:

git submodule update --init

Atualizando Submódulos para a Versão Remota Mais Recente

Se você deseja atualizar um submódulo para o commit mais recente em seu repositório remoto, você pode usar:

cd ~/project/main-repo
git submodule update --remote libs/libgit2-backends

Este comando busca as últimas alterações do repositório remoto e atualiza o submódulo. Você deve ver uma saída indicando que o Git está buscando alterações.

Após executar este comando, vamos verificar o status do submódulo:

git submodule status

Você notará que a saída agora mostra um sinal de mais (+) no início, indicando que o commit verificado do submódulo difere do que está registrado no repositório principal:

+abcdef1234567890abcdef1234567890abcdef12 libs/libgit2-backends (origin/HEAD)

Para confirmar as alterações em seu repositório principal, execute:

git status

Você deve ver uma saída indicando que o submódulo foi modificado:

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   libs/libgit2-backends (new commits)

Commitando a Referência do Submódulo Atualizado

Para registrar o estado do submódulo atualizado em seu repositório principal, você precisa adicionar e commitar as alterações:

git add libs/libgit2-backends
git commit -m "Update libgit2-backends submodule to latest version"

A saída deve indicar que você committou com sucesso a nova referência do submódulo.

Verificando o Status Atualizado

Após commitar a referência do submódulo atualizada, vamos verificar o status novamente:

git submodule status

A saída não deve mais ter um sinal de mais no início, indicando que o submódulo agora está sincronizado com o que está registrado no repositório principal:

 abcdef1234567890abcdef1234567890abcdef12 libs/libgit2-backends (origin/HEAD)

Entendendo as Opções de Atualização do Submódulo

O comando git submodule update possui várias opções que controlam como as atualizações são realizadas:

  • --remote: Atualiza para o commit mais recente na branch de rastreamento remota
  • --merge: Faz merge das alterações se a branch atual estiver atrás da remota
  • --rebase: Faz rebase das alterações se a branch atual estiver atrás da remota
  • --recursive: Atualiza submódulos aninhados também

Para a maioria dos casos de uso básico, git submodule update --remote é suficiente.

Trabalhando com Mudanças em Submódulos

Às vezes, você precisa trabalhar com mudanças dentro de um submódulo. Nesta etapa, aprenderemos como fazer e gerenciar mudanças dentro de submódulos.

Para trabalhar com um submódulo, você precisa navegar para o seu diretório:

cd ~/project/main-repo/libs/libgit2-backends

A partir daqui, você pode usar comandos Git padrão para visualizar informações sobre o repositório do submódulo:

git status
git log -3 --oneline

O comando git status mostra o estado atual do repositório do submódulo, e git log mostra os commits recentes.

Fazendo Mudanças em um Submódulo

Vamos fazer uma mudança simples em um arquivo no submódulo. Primeiro, vamos criar um novo arquivo:

echo "## My notes on libgit2-backends" > NOTES.md

Agora vamos verificar o status da nossa mudança:

git status

Você deve ver uma saída indicando que você tem um arquivo não rastreado:

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        NOTES.md

Vamos adicionar e commitar essa mudança ao submódulo:

git add NOTES.md
git commit -m "Add notes file"

Você deve ver uma saída confirmando seu commit dentro do submódulo.

Verificando o Status do Repositório Principal

Agora, vamos voltar ao repositório principal e verificar o status:

cd ~/project/main-repo
git status

Você deve ver uma saída indicando que o submódulo foi modificado:

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   libs/libgit2-backends (new commits)

Commitando Mudanças no Submódulo no Repositório Principal

Para registrar o novo estado do submódulo em seu repositório principal, você precisa adicionar e commitar as mudanças:

git add libs/libgit2-backends
git commit -m "Update libgit2-backends with notes file"

A saída deve indicar que você committou com sucesso a nova referência do submódulo.

Visualizando Mudanças Detalhadas no Submódulo

Para ver informações mais detalhadas sobre as mudanças nos submódulos, você pode usar:

git diff --submodule

Este comando mostra a faixa de commits que foram adicionados ou removidos em cada submódulo alterado.

Resumo de Como Trabalhar com Mudanças em Submódulos

Ao trabalhar com mudanças em um submódulo, lembre-se deste fluxo de trabalho:

  1. Navegue para o diretório do submódulo
  2. Faça e commite as mudanças dentro do submódulo
  3. Retorne ao repositório principal
  4. Adicione e commite a referência do submódulo atualizada

Este processo de commit em duas etapas (primeiro no submódulo, depois no repositório principal) é essencial para rastrear corretamente as mudanças nos submódulos.

Resumo

Neste tutorial, você aprendeu como trabalhar com submódulos Git, focando em verificar seu status e fazer atualizações. Aqui está o que você realizou:

  1. Criou um repositório principal e adicionou um submódulo a ele
  2. Aprendeu como verificar o status dos submódulos usando vários comandos Git
  3. Atualizou um submódulo para a versão mais recente de seu repositório remoto
  4. Fez alterações dentro de um submódulo e rastreou adequadamente essas alterações no repositório principal

Os submódulos Git fornecem uma maneira poderosa de incluir repositórios externos em seus projetos, permitindo que você gerencie as dependências de forma eficiente. Ao entender como verificar seu status e gerenciar atualizações, você pode garantir que seu projeto permaneça devidamente sincronizado com suas dependências.

Comandos-chave para lembrar:

  • git submodule status - Verifica o status atual dos submódulos
  • git submodule update --remote - Atualiza os submódulos para suas versões mais recentes
  • git add <submodule-path> - Prepara as alterações para a referência de um submódulo
  • git diff --submodule - Visualiza as alterações detalhadas nos submódulos

Com essas habilidades, você pode gerenciar efetivamente repositórios Git que incorporam código externo por meio de submódulos.