Git
Português (Brasil) ▾ Topics ▾ Latest version ▾ git-submodule last updated in 2.47.0

NOME

git-submodule - Inicialize, atualize ou inspecione os submódulos

RESUMO

git submodule [--quiet] [--cached]
git submodule [--quiet] add [<opções>] [--] <repository> [<caminho>]
git submodule [--quiet] status [--cached] [--recursive] [--] [<caminho>…​]
git submodule [--quiet] init [--] [<caminho>…​]
git submodule [--quiet] deinit [-f|--force] (--all|[--] <caminho>…​)
git submodule [--quiet] update [<opções>] [--] [<caminho>…​]
git submodule [--quiet] set-branch [<opções>] [--] <caminho>
git submodule [--quiet] set-url [--] <caminho> <newurl>
git submodule [--quiet] summary [<opções>] [--] [<caminho>…​]
git submodule [--quiet] foreach [--recursive] <command>
git submodule [--quiet] sync [--recursive] [--] [<caminho>…​]
git submodule [--quiet] absorbgitdirs [--] [<caminho>…​]

DESCRIÇÃO

Inspeciona, atualiza e gerencia os submódulos.

Para mais informações sobre submódulos, consulte gitsubmodules[7].

COMANDOS

Sem argumentos, mostra a condição geral dos submódulos existentes. Vários subcomandos estão disponíveis para realizar operações nos submódulos.

add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--] <repository> [<path>]

Adicione o repositório informado como um submódulo no caminho especificado ao conjunto de alterações para ser feito o commit ao lado do projeto atual: o projeto atual é chamado de "superproject".

<repositório> é a URL do repositório de origem do novo submódulo. Pode ser uma URL absoluta ou (se começar com ./ ou ../), o local relativo ao repositório remoto padrão do superprojeto (observe que, para especificar um repositório foo.git onde está localizado um superprojeto bar.git, você terá que usar ../foo.git em vez de ./foo.git - como seria de se esperar ao seguir as regras para URLs relativas - porque a avaliação de URLs relativas no Git é idêntica à de diretórios relativos).

O ramo remoto padrão é o ramo remote do ramo rastreado remotamente no ramo atual. Se não houver uma ramificação de rastreamento remoto ou se o HEAD for desanexado, a origin será considerada o ramo remoto predefinido. Se o superprojeto não tiver um ramo remoto predefinido configurado, o superprojeto será o seu próprio topo autoritativo e o diretório de trabalho atual será usado em seu lugar.

O argumento opcional <caminho> é o local relativo para que o submódulo clonado exista no superprojeto. Caso o <caminho> não seja informado, a parte canônica do repositório da origem será utilizada ("repo" para o "/path/to/repo.git" e "foo" para o "host.xz:foo/.git"). Caso o <caminho> exista e já for um repositório Git válido, ele será preparado para o commit sem clonagem. O <caminho> também é utilizado como o nome lógico do sub-módulo nas suas entradas de configuração, a menos que --name seja utilizado para definir um nome lógico.

A URL informada é registrado em .gitmodules para ser usado por usuários subsequentes que clonarem o superprojeto. Se a URL for informada em relação ao repositório do superprojeto, presume-se que os repositórios do superprojeto e do submódulo serão mantidos juntos no mesmo local relativo, e somente o URL do superprojeto precisará ser fornecido. O git-submodule localizará corretamente o submódulo usando a URL relativa em .gitmodules.

If --ref-format <format> is specified, the ref storage format of newly cloned submodules will be set accordingly.

status [--cached] [--recursive] [--] [<caminho>…​]

Exiba a condição geral dos submódulos. Irá exibir o SHA-1 do commit registrado atualmente para cada submódulo, junto com o caminho do submódulo e a saída do comando git description para o SHA-1. Cada SHA-1 provavelmente será prefixado com - caso o submódulo não seja inicializado,+ caso o commit verificado do submódulo atual não coincida com o SHA-1 encontrado no índice do repositório que contenha o U caso o submódulo tenha conflitos de mesclagem.

Caso a opção --cached seja utilizado, este comando exibirá o SHA-1 registrado no superprojeto para cada sub-módulo.

Caso --recursive seja utilizado, este comando será recusado no submódulos aninhados e exibirá a sua condição geral também.

Caso apenas tenha interesse nas alterações dos submódulos inicializados no momento em relação ao commit registrado no índice ou no HEAD, o git-status[1] e o git-diff[1] também disponibilizarão essas informações (e podem também relatar as alterações na árvore de trabalho de um submódulo).

init [--] [<caminho>…​]

Inicialize os submódulos registrados no índice (que foram adicionados e confirmados em outro lugar) definindo submodule.$name.url em .git/config, usando a mesma configuração de .gitmodules como modelo. Se o URL for relativo, ele será resolvido usando o ramo remoto padrão. Se não houver um ramo remoto padrão, o repositório atual será considerado upstream.

Os argumentos opcionais <caminho> limitam onde os submódulos serão inicializados. Se nenhum caminho for especificado e o submodule.active tiver sido configurado, os submódulos configurados para estarem ativos serão inicializados; caso contrário, todos os submódulos serão inicializados.

Ele também copiará o valor de submodule.$name.update, se estiver presente no arquivo .gitmodules, para .git/config, mas (1) esse comando não altera as informações existentes em .git/config e (2) submodule.$name.update definido como um comando personalizado não é copiado por motivos de segurança.

Em seguida, você pode personalizar os URLs do clone do submódulo em .git/config para a sua configuração local e prosseguir com git submodule update; você também pode usar git submodule update --init sem a etapa init explícita se não tiver a intenção de personalizar nenhum local do submódulo.

Consulte o subcomando add para obter a definição predefinida do ramo remoto.

deinit [-f|--force] (--all|[--] <caminho>…​)

Cancele o registro dos submódulos informado, ou seja, remova toda a seção submodule.$name do .git/config junto com a sua árvore de trabalho. Outras futuras chamadas para o comando git submodule update, git submodule foreach e git submodule sync irão ignorar todos os submódulos não registrados até que sejam inicializados novamente, então utilize este comando caso não queira mais fazer uma verificação do submódulo na sua árvore de trabalho local.

O comando exibe um erro quando for executado sem o pathspec em vez de cancelar a inicialização de tudo, evitando erros.

Caso --force seja utilizado, a árvore de trabalho do submódulo será removida, mesmo que contenha alterações locais.

Caso realmente deseja remover um submódulo do repositório e fazer o commit em vez disso utilize git-rm[1] Para opções de remoção consulte gitsubmodules[7].

update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--ref-format <format>] [--depth <depth>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--filter <filter-spec>] [--] [<path>…​]

Atualize os submódulos registrados para que correspondam ao que o superprojeto espera, clonando os submódulos ausentes, obtendo os commits ausentes nos submódulos e atualizando a árvore de trabalho dos submódulos. A "atualização" pode ser feita de várias maneiras, dependendo das opções da linha de comando e do valor da variável de configuração submodule.<nome>.update. A opção de linha de comando tem precedência sobre a variável de configuração. Se nenhum dos dois for fornecido, será realizado um checkout. (Observação: o que está no arquivo .gitmodules é irrelevante neste momento; consulte o comando git submodule init acima para saber como o .gitmodules é usado). Os procedimentos de atualização update compatíveis tanto com a linha de comando quanto com a configuração submodule.<nome>.update são:

checkout

o commit registrado no superprojeto será verificado no submódulo do HEAD desanexado.

Caso a opção --force utilizado, o submódulo será averiguado (utilizando git checkout --force), mesmo que o commit definido no índice do repositório que o contenha já coincida com os commits que já foram verificados.

rebase

a fundação do submódulo do ramo atual será refeito no commit registrado no superproject.

merge

o commit registrado no superprojeto será mesclado no submódulo do ramo atual.

Os procedimentos de atualização a seguir têm limitações adicionais:

comando personalizado

para executar comandos arbitrários com o ID do commit como argumento. Especificamente, se a variável de configuração submodule.<nome>.update for definida como !custom command, o nome do objeto do commit registrado no superprojeto para o submódulo será anexado à string custom command e depois executado. Observe que esse mecanismo não é compatível com o arquivo .gitmodules ou com a linha de comando.

none

o submódulo não é atualizado. Esse procedimento de atualização não é permitido na linha de comando.

Se o submódulo ainda não foi inicializado e você apenas deseja utilizar a configuração armazenada no .gitmodules, você pode inicializar automaticamente o submódulo com a opção --init.

Caso a opção --recursive seja utilizada, este comando recursará nos submódulos registrados e atualizará todos os submódulos aninhados.

If --ref-format <format> is specified, the ref storage format of newly cloned submodules will be set accordingly.

Se a opção --filter <spec-do-filtro> for especificado, o filtro de clone parcial fornecido será aplicado ao submódulo. Consulte o git-rev-list[1] para obter detalhes sobre as especificações do filtro.

set-branch (-b|--branch) <ramo> [--] <caminho>
set-branch (-d|--default) [--] <caminho>

Define o submódulo como predefinido nos ramos monitorados remotamente. A opção --branch permite que o nome do ramo remoto seja definido. A opção --default remove a chave da configuração submodule.<nome>.branch, que faz com que a predefinição do ramo monitorado seja o HEAD remoto.

set-url [--] <caminho> <newurl>

Define a URL do submódulo informado para <newurl> . Em seguida, sincronize automaticamente a nova configuração da URL remota do submódulo.

summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<caminho>…​]

Exiba o resumo do commit entre o commit informado (a predefinição retorna para HEAD) e a árvore de trabalho/índice. Para um submódulo em questão, são exibidas uma série de commit do submódulo entre o commit do super projeto e o índice ou a árvore de trabalho (alternada por --cached). Caso a opção --files seja utilizada, exiba a série dos commits no submódulo entre o índice do super projeto e a árvore de trabalho do submódulo (esta opção não permite a utilização da opção --cached ou para informar um commit de forma explícita).

O uso da opção --submodule=log com git-diff[1] também fornecerá estas informações.

foreach [--recursive] <comando>

Avalia um comando de shell arbitrário em cada submódulo verificado. O comando tem acesso às variáveis $name, $sm_path, $displaypath, $sha1 e $toplevel: O $name é o nome da seção relevante do submódulo em .gitmodules, $sm_path é o caminho do submódulo conforme registrado no superprojeto imediato, $displaypath contém o caminho relativo do diretório de trabalho atual para o diretório raiz do submódulo, $sha1 é o commit conforme registrado no superprojeto imediato e $toplevel é o caminho absoluto para o topo imediato do superprojeto. Observe que, para evitar conflitos com $PATH no Windows, a variável $path agora é um sinônimo obsoleto da variável $sm_path. Todos os submódulos definidos no superprojeto, mas que não tenham sido verificados, são ignorados por esse comando. A menos que seja informado a opção --quiet, o foreach imprime o nome de cada submódulo antes de avaliar o comando. Se a opção --recursive for usada, os submódulos serão percorridos recursivamente (ou seja, o comando do shell fornecido também será avaliado nos submódulos aninhados). Um retorno diferente de zero do comando em qualquer submódulo faz com que o processamento seja encerrado. Isso pode ser substituído pela adição de || : ao final do comando.

Como um exemplo, o comando abaixo exibirá o caminho e a averiguação atual do commit para cada submódulo:

git submodule foreach 'echo $sm_path `git rev-parse HEAD`'
sync [--recursive] [--] [<caminho>…​]

Sincroniza a configuração da URL remota dos submódulos com o valor definido em .gitmodules. Afetará apenas os submódulos que já possuem uma entrada da URL no .git/config (é o caso quando eles são inicializados ou foram adicionados recentemente). É útil quando as URLs do submódulo mudam a upstream e você precisa atualizar os seus repositórios locais de acordo.

O comando git submodule sync sincroniza todos os submódulos enquanto o comando git submodule sync - A sincroniza apenas o submódulo "A".

Caso a opção --recursive seja utilizada, este comando recursará nos submódulos registrados e sincronizará todos os submódulos aninhados.

absorbgitdirs

Caso um diretório git de um submódulo estiver dentro dele, mova o diretório git do submódulo para o caminho $GIT_DIR/modules do superprojeto, conecte o diretório git, o seu diretório de trabalho, definindo core.worktree e adicionando um Arquivo .git apontando para o diretório git incorporado no diretório git dos superprojetos.

Um repositório que foi clonado de forma independente e posteriormente adicionado como um submódulo ou com configurações antigas, que possua o diretório git dentro do submódulo, em vez de estar incorporado ao diretório git dos superprojetos.

A predefinição deste comando é ser recursivo.

OPÇÕES

-q
--quiet

Exiba apenas as mensagens de erro.

--progress

Essa opção só é válida para o comando add e update. A condição geral do progresso é relatada no fluxo de erro padrão por padrão quando ele é anexado a um terminal, a menos que a opção -q seja especificada. Esta opção impõem a condição geral de progresso, ainda que o fluxo de erro predefinido não seja direcionado a um terminal.

--all

Esta opção só é válida para o comando deinit. Cancele o registro de todos os submódulos na árvore de trabalho.

-b <ramo>
--branch <ramo>

O ramo do repositório que será adicionado como um submódulo. O nome do ramo é gravado como submodule.<nome>.branch em .gitmodules para update --remote. Um valor especial . é usado para indicar que o nome do ramo no submódulo deve ser o mesmo nome do ramo atual no repositório atual. Se a opção não for especificada, a predefinição é o HEAD remoto.

-f
--force

Esta opção só é válida para os comandos add, deinit e update. Ao executar add, permite adicionar um caminho de submódulo que de outra forma seria ignorado. Ao executar o deinit, as árvores de trabalho do submódulo serão removidas mesmo que contenham alterações locais. Ao executar o update (apenas eficaz com o procedimento de checkout), descarte as alterações locais nos submódulos ao mudar para um commit diferente; e execute sempre uma operação de checkout no submódulo, mesmo que o commit listado no índice do repositório que o contém corresponda ao commit verificado no submódulo.

--cached

Esta opção só é válida para os comandos status`e `summary. Esses comandos normalmente usam o commit encontrado no submódulo HEAD, mas com essa opção, o commit armazenado no índice é usado.

--files

Esta opção só é válida para o comando summary. Quando esta opção é utilizada o comando compara o commit no índice em conjunto com o que está no submódulo HEAD.

-n
--summary-limit

Esta opção só é válida para o comando summary. Limitar o tamanho do resumo summary (quantidade de commits mostrados no total). Usar 0 desativará o resumo summary; um número negativo significa ilimitado (o padrão). Este limite só se aplica aos submódulos alterados. O tamanho é sempre limitado a 1 para submódulos adicionados/excluídos/alterados por tipo.

--remote

Esta opção só é válida para o comando update. Em vez de usar o SHA-1 registrado do superprojeto para atualizar o submódulo, use a condição do submódulo da ramificação rastreada remotamente. O "remoto" usado é o ramo da ramificação remota (branch.<nome>.remote), cujo padrão é origin. A ramificação remota usada tem como padrão o HEAD remoto, mas o nome da ramificação pode ser substituído pela configuração da opção submodule.<nome>.branch em .gitmodules ou .git/config (tendo precedência o .git/config).

Isso funciona para qualquer um dos procedimentos de atualização compatíveis (--checkout, --rebase, etc.). A única alteração é a origem do SHA-1 de destino. Por exemplo, a opção submodule update --remote --merge mesclará as alterações do submódulo upstream nos submódulos, enquanto a opção submodule update --merge mesclará as alterações do gitlink do superprojeto nos submódulos.

Para garantir a condição atual da ramificação de rastreamento, a opção update --remote busca pelo repositório remoto do submódulo antes de calcular o SHA-1. Se não quiser buscar, você deve usar a opção submodule update --remote --no-fetch.

Use esta opção para integrar as alterações do subprojeto upstream com o HEAD atual do seu submódulo. Como alternativa, você pode executar o git pull a partir do submódulo, o que é equivalente, exceto pelo nome do ramo remoto: a opção update --remote usa o repositório upstream predefinido e o submodule.<nome>.branch, enquanto o comando git pull usa o branch.<nome>.merge do submódulo. Prefira submodule.<nome>.branch se quiser distribuir o ramo upstream predefinido com o superprojeto e branch.<nome>.merge se quiser uma sensação mais nativa ao trabalhar no próprio submódulo.

-N
--no-fetch

Esta opção só é válida para o comando update. Não busque novos objetos no site remoto.

--checkout

Esta opção só é válida para o comando update. Faça o checkout do commit registrado no superprojeto num HEAD desanexado no submódulo. Esse é o comportamento predefinido; o principal uso dessa opção é substituir submodule.$name.update quando definido com um valor diferente do checkout. Se a chave submodule.$name.update não estiver explicitamente definida ou estiver definida como checkout, essa opção será implícita.

--merge

Esta opção só é válida para o comando update. Mesclar o commit registrado no superprojeto na ramificação atual do submódulo. Se essa opção for fornecida, o HEAD do submódulo não será desanexado. Se uma falha de mesclagem impedir este processo, você terá que resolver os conflitos resultantes dentro do submódulo com as ferramentas usuais de resolução de conflitos. Se a chave submodule.$name.update estiver definida como merge, esta opção estará implícita.

--rebase

Esta opção só é válida para o comando update. Faça o rebase do ramo atual para o commit registrado no superprojeto. Se essa opção for fornecida, o HEAD do submódulo não será desanexado. Se uma falha de mesclagem impedir este processo, você terá que resolver estas falhas com o comando git-rebase[1]. Se a chave submodule.$name.update estiver definida como rebase, esta opção estará implícita.

--init

Esta opção só é válida para o comando update. Inicialize todos os submódulos para onde o git submodule init não foi chamado até o momento antes da atualização.

--name

Esta opção só é válida para o comando add. Define o nome do submódulo para a carreira de caracteres informada em vez de padronizar o seu caminho. O nome deve ser válido como um nome de diretório e não pode terminar com um /.

--reference <repositório>

Essa opção só é válida para o comando add e update. Esses comandos às vezes precisam clonar um repositório remoto. Nesse caso, essa opção será encaminhada para o comando git-clone[1].

OBSERVAÇÃO: Jamais utilize esta opção, a menos que você tenha lido com muita atenção as observações para git-clone[1], --reference, --shared, e --dissociate.

--dissociate

Essa opção só é válida para o comando add e update. Esses comandos às vezes precisam clonar um repositório remoto. Nesse caso, essa opção será encaminhada para o comando git-clone[1].

OBSERVAÇÃO: consulte a OBSERVAÇÃO sobre a opção --reference.

--recursive

Essa opção só é válida para os comandos foreach, update, status e sync. Percorrer os submódulos recursivamente. A operação é realizada não apenas nos submódulos do repositório atual, mas também em quaisquer submódulos aninhados dentro desses submódulos (e assim por diante).

--depth

Esta opção é válida para os comandos add e update. Cria um clone superficial (shallow) com um histórico truncado para o número especificado de revisões. Consulte git-clone[1]

--[no-]recommend-shallow

Esta opção só é válida para o comando update. O clone inicial de um submódulo usará o submodule.<nome>.shallow recomendado, conforme fornecido pelo arquivo .gitmodules predefinido. Para ignorar as sugestões, use a opção --no-recommend-shallow.

-j <n>
--jobs <n>

Esta opção só é válida para o comando update. Clonar os novos submódulos em paralelo com a mesma quantidade de trabalhos. A predefinição é o que estiver em submodule.fetchJobs.

--[no-]single-branch

Esta opção só é válida para o comando update. Clone apejas um ramo durante a atualização: HEAD ou um ramo especificado pela opção --branch.

<caminho>…​

Os caminhos para os submódulos. Quando especificada, esta opção restringirá o comando a operar apenas nos submódulos encontrados nos caminhos especificados. (Esta é uma exigência do argumento add).

ARQUIVOS

Ao inicializar os submódulos, um arquivo .gitmodules no diretório do topo do repositório que o contém é usado para encontrar a URL de cada submódulo. Esta deve ser formatada da mesma forma que $GIT_DIR/config. A chave para cada URL de submódulo é submodule.$name.url. Para mais detalhes consulte gitmodules[5].

GIT

Parte do conjunto git[1]

scroll-to-top