Git
Português (Brasil) ▾ Topics ▾ Latest version ▾ git-submodule last updated in 2.33.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, exiba a condição geral dos submódulos já existentes. Vários subcomandos estão disponíveis para execução das operações nos submódulos.

add [-b <ramo>] [-f|--force] [--name <nome>] [--reference <repositório>] [--depth <profundidade>] [--] <repositório> [<caminho>]

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".

O <repositório> é o URL do repositório de origem do novo submódulo. Este pode ser um URL absoluto, ou (se começar com ./ ou ../), a localização relativa ao repositório predefinido do superprojeto remoto (Por favor note que para especificar um repositório foo.git que está localizado bem ao lado de um superproject bar.git, você terá que usar ../foo.git em vez de ./foo.git - como se pode esperar quando se seguem as regras para URLs relativas - porque a avaliação das URLs relativas no Git é idêntica à dos diretórios relativos).

A predefinição do ramo remoto é que ele seja monitorado pelo ramo atual. Se esse ramo monitorado remotamente não exista ou o HEAD esteja desconectado, a "origin" será assumida como o ramo remoto predefinido. Caso o superprojeto não tenha predefinido um ramo remoto configurado, o superprojeto será o seu próprio upstream autoritativo e será utilizado o diretório de trabalho atual.

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 é registrada no .gitmodules para a utilização dos subsequentes usuários que clonam o superprojeto. Caso a URL seja informada com relação ao repositório do superprojeto, a presunção que os repositórios do superprojeto e dos submódulos serão mantidos juntos, peóximos do mesmo local, somente a URL do superprojeto precisará ser informada. O comando git-submodule localizará corretamente o submódulo utilizando uma URL relativa em .gitmodules.

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 onde os commits foram feitos em outros lugares) configurando o submodule.$name.url no .git/config. Ele usa a mesma configuração do .gitmodules como um modelo. Caso a URL seja relativa, será resolvido utilizando ramo remoto predefinido. Caso não nenhum ramo remoto seja predefinido, o repositório atual será reconhecido como sendo a upstream.

Os argumentos opcionais do <caminho> limitam quais foram os submódulos que serão inicializados. Caso nenhum caminho seja informado e o submodule.active tenha sido configurado, apenas os submódulos configurados para estarem ativos serão inicializados, caso contrário, todos os submódulos serão.

Quando presente, também copiará o valor do submodule.$name.update. Este comando não altera as informações existentes no .git/config. É possível personalizar os clones dos submódulos das URLs no .git/config para sua configuração local e prosseguir para o git submodule update; tamém é possível utilizar o git submodule update --init sem a etapa init de forma explícita caso não pretenda personalizar nenhum local do submodule.

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 <repositório>] [--depth <profundidade>] [--recursive] [--jobs <n>] [--[no-]single-branch] [--] [<caminho>…​]

Atualize os submódulos registrados para que coincidam com o que o superprojeto espera, clonando os submódulos ausentes, capturando os commit que estejam 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 da linha de comando tem precedência sobre a variável de configuração. Caso nenhum seja informado, um checkout é realizado. Os procedimentos de atualização compatíveis tanto na linha de comando quanto na configuração submodule.<nome>.update são:

checkout

o commit registrado no superprojeto será verificado no submódulo em um 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 superprojeto.

merge

o commit registrado no superprojeto será mesclado na ramificação atual no submódulo.

Os seguintes procedimentos de atualização estão disponíveis apenas através da variável de configuração submodule.<nome>.update:

comando personalizado

comando shell arbitrário que utiliza um único argumento (o sha1 do commit registrado no superprojeto) é executado. Quando submodule.<nome>.update está definido como !command, o comando personalizado é o restante após o ponto de exclamação.

none

o submódulo não é atualizado.

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.

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 arbitrário do shell em cada sub-módulo averiguado. O comando tem acesso às variáveis $name, $sm_path, $displaypath, $sha1 e $toplevel: $name é o nome da seção do submódulo relevante no .gitmodules, $sm_path é o caminho do submódulo conforme foi diretamente registrado no superprojeto, $displaypath contém o caminho relativo do diretório de trabalho atual para o diretório raiz dos sub-módulos, $sha1 é o commit conforme registrado diretamente no superprojeto e $toplevel é o caminho absoluto e direto para o nível mais alto 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 sem averiguação, são ignorados por este comando. A menos que seja utilizado a opção --quiet, o foreach imprime o nome de cada submódulo antes de avaliar o comando. Caso a opção --recursive seja utilizada, os submódulos serão percorridos de forma recursiva (ou seja, o comando shell informado também será avaliado nos submódulos aninhados). Um retorno do comando diferente de zero em qualquer submódulo, faz com que o processamento seja finalizado. Isso pode ser alterado adicionando || : até o 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

Esta opção só é válida para os comandos add e update. É predefinido que a condição geral do progresso seja relatada no fluxo de erros quando estiver conectado em um terminal, a menos que -q seja utilizado. Esta opção impõem a condição geral do progresso, mesmo que o fluxo de erro predefinido não seja direcionado para 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 para ser adicionado como um submódulo. O nome do ramo é registrado como submodule.<nome>.branch no .gitmodules para update --remote. Um valor especial de . é utilizado para indicar que o nome do ramo no submódulo deve ser o mesmo nome como o da ramificação atual, no repositório atual. Caso a opção não seja utilizada, a predefinição retorna para o HEAD remoto.

-f
--force

Esta opção só é válida para os comandos add, deinit e update. Ao executar add, permita adicionar um caminho ignorado do submódulo. Ao executar o deinit, as árvores de trabalho do submódulo serão removidos mesmo que contenham alterações locais. Ao executar update (efetiva apenas com o procedimento de averiguação), descarte as alterações locais nos submódulos durante a alternância para um commit diferente; sempre execute uma operação de averiguação no submódulo, mesmo que o commit listado no índice do repositório coincida com o commit averiguado no submódulo.

--cached

Esta opção só é válida para os comandos status e summary. Esses comandos normalmente utilizam o commit encontrado no submódulo HEAD, porém o commit armazenado no índice que é utilizado em seu lugar.

--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. Limite o tamanho do resumo (quantidade de commits exibidos no total). O número 0 desativa o resumo; um número negativo significa ilimitado (já predefinido). Este limite se aplica apenas aos submódulos modificados. O tamanho é sempre limitado a 1 para os submódulos adicionado/excluído/tipo alterado.

--remote

Esta opção só é válida para o comando update. Em vez de utilizar o SHA-1 registrado no superprojeto para atualizar o submódulo, utilize a condição geral do submódulo do ramo monitorado remotamente. O ramo remoto utilizado é o ramo (branch.<nome>.remote) predefinido para origin. O ramo remoto costumava retornar para o HEAD remoto, porém o nome do ramo pode ser substituído ao definir a opção submodule.<nome>.branch ou entre .gitmodules ou .git/config (onde .git/config tem prioridade).

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

Para garantir uma condição de monitoramento da ramificação atual, update --remote captura o repositório remoto do submódulo antes de calcular o seu SHA-1. Caso não queira capturar, utilize submodule update --remote --no-fetch.

Use esta opção para integrar as alterações a partir do subprojeto upstream ao HEAD atual do seu submódulo. Como alternativa, você pode executar o comando git pull a partir do submódulo, que é equivalente, exceto pelo nome do ramo remoto: update --remote utiliza o repositório upstream predefinido e submodule.<nome>.branch, enquanto git pull utiliza o submódulo branch.<nome>.merge. Prefira o submodule.<nome>.branch caso queira distribuir a ramificação upstream predefinido com o superprojeto e branch.<nome>.merge caso queira 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 capture os novos objetos do site remoto.

--checkout

Esta opção só é válida para o comando update. Faça a averiguação do commit registrado no superprojeto em um HEAD desanexado no submódulo. Este é o comportamento predefinido, a utilização principal desta opção é substituir o submodule.$name.update quando definido como um valor diferente do checkout. Caso a chave do submodule.$name.update não esteja nem explicitamente configurada ou definida com checkout (para averiguação), então esta opção se torna implícita.

--merge

Esta opção só é válida para o comando update. Mescle o commit registrado no superprojeto do ramo atual do submódulo. Caso esta opção seja utilizada, o HEAD do submódulo não será desconectado. Caso uma mesclagem falhe e interrompa este processo, será necessário resolver os conflitos resultantes no submódulo com as ferramentas habituais da resolução de conflitos. Caso a chave submodule.$name.update esteja configurada para mesclar, então esta opção se torna implícita.

--rebase

Esta opção só é válida para o comando update. Reorganize a fundação do ramo atual no commit registrado no superprojeto. Caso esta opção seja utilizada, o HEAD do submódulo não será desconectado. Caso uma mesclagem falhe e interrompa este processo, será necessário resolver os conflitos resultantes com git-rebase[1]. Caso a chave submodule.$name.update esteja definida como rebase, então esta opção se torna implícita.

--init

Esta opção só é válida para o comando update. Inicialize todos os submódulos para os quais o comando "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>

Esta opção só é válida para os comandos add e update. Às vezes estes comandos precisam clonar um repositório remoto. Neste caso, esta opção será passada ao comando git-clone[1].

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

--dissociate

Esta opção só é válida para os comandos add e update. Às vezes estes comandos precisam clonar um repositório remoto. Neste caso, esta opção será passada ao comando git-clone[1].

OBSERVAÇÃO: Consulte a OBSERVAÇÃO para a opção --reference.

--recursive

Esta opção só é válida para os comandos foreach, update, status e sync. Transponha os submódulos recursivamente. A operação é executada não apenas nos submódulos do repositório atual, mas também em qualquer outro submódulo aninhado dentro desses submódulos (e assim por diante).

--depth

Esta opção é válida para os comandos add e update. Crie uma clonagem superficial com um histórico truncado para uma quantidade determinada 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 por predefinição, utilizará o submodule.<nome>.shallow recomendado conforme é fornecido pelo arquivo .gitmodules. Para ignorar as sugestões, utilize --no-recommend-shallow.

-j <n>
--jobs <n>

Esta opção só é válida para o comando update. Clone novos submódulos em paralelo com a mesmo quantidade de trabalhos. A predefinição retorna para a configuração existente em submodule.fetchJobs.

--[no-]single-branch

Esta opção só é válida para o comando update. Clone apenas uma ramificação durante a atualização: HEAD ou uma definida pela opção --branch.

<caminho>…​

Caminhos para o submódulo(s). Quando for utilizado, restringe o comando a operar apenas nos submódulos encontrados nos caminhos informados. (É obrigatório a utilização desta opção com o add).

ARQUIVOS

Durante a atualização dos submódulos um arquivo .gitmodules fica no topo do diretório do repositório que o contenha, é utilizado para encontrar a URL de cada submódulo. Este arquivo deve ser formatado da mesma maneira que $GIT_DIR/config. A chave para cada URL do submódulo é submodule.$name.url. Para mais detalhes consulte gitmodules[5].

GIT

Parte do conjunto git[1]