From: Junio C Hamano Date: Mon, 8 Aug 2011 19:33:35 +0000 (-0700) Subject: Merge branch 'jl/submodule-status-summary-doc' X-Git-Tag: v1.7.7-rc0~43 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/460940f99766ed547cc48f4c574acdc8c258e845?ds=inline;hp=-c Merge branch 'jl/submodule-status-summary-doc' * jl/submodule-status-summary-doc: Documentation/submodule: add command references and update options --- 460940f99766ed547cc48f4c574acdc8c258e845 diff --combined Documentation/git-submodule.txt index 0ec85742dd,3b05498c10..67cf5f0f8b --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@@ -15,7 -15,8 +15,8 @@@ SYNOPSI 'git submodule' [--quiet] init [--] [...] 'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase] [--reference ] [--merge] [--recursive] [--] [...] - 'git submodule' [--quiet] summary [--cached|--files] [--summary-limit ] [commit] [--] [...] + 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) ] + [commit] [--] [...] 'git submodule' [--quiet] foreach [--recursive] 'git submodule' [--quiet] sync [--] [...] @@@ -78,9 -79,7 +79,9 @@@ to exist in the superproject. If is the URL of the new submodule's origin repository. This may be either an absolute URL, or (if it begins with ./ or ../), the location relative to the superproject's origin -repository. +repository. If the superproject doesn't have an origin configured +the superproject is its own authoritative upstream and the current +working directory is used instead. + is the relative location for the cloned submodule to exist in the superproject. If does not exist, then the @@@ -108,8 -107,13 +109,13 @@@ status: repository and `U` if the submodule has merge conflicts. This command is the default command for 'git submodule'. + - If '--recursive' is specified, this command will recurse into nested + If `--recursive` is specified, this command will recurse into nested submodules, and show their status as well. + + + If you are only interested in changes of the currently initialized + submodules with respect to the commit recorded in the index or the HEAD, + linkgit:git-status[1] and linkgit:git-diff[1] will provide that information + too (and can also report changes to a submodule's work tree). init:: Initialize the submodules, i.e. register each submodule name @@@ -125,26 -129,29 +131,29 @@@ update:: Update the registered submodules, i.e. clone missing submodules and checkout the commit specified in the index of the containing repository. - This will make the submodules HEAD be detached unless '--rebase' or - '--merge' is specified or the key `submodule.$name.update` is set to + This will make the submodules HEAD be detached unless `--rebase` or + `--merge` is specified or the key `submodule.$name.update` is set to `rebase` or `merge`. + If the submodule is not yet initialized, and you just want to use the setting as stored in .gitmodules, you can automatically initialize the - submodule with the --init option. + submodule with the `--init` option. + - If '--recursive' is specified, this command will recurse into the + If `--recursive` is specified, this command will recurse into the registered submodules, and update any nested submodules within. summary:: Show commit summary between the given commit (defaults to HEAD) and working tree/index. For a submodule in question, a series of commits in the submodule between the given super project commit and the - index or working tree (switched by --cached) are shown. If the option - --files is given, show the series of commits in the submodule between + index or working tree (switched by `--cached`) are shown. If the option + `--files` is given, show the series of commits in the submodule between the index of the super project and the working tree of the submodule - (this option doesn't allow to use the --cached option or to provide an + (this option doesn't allow to use the `--cached` option or to provide an explicit commit). + + + Using the `--submodule=log` option with linkgit:git-diff[1] will provide that + information too. foreach:: Evaluates an arbitrary shell command in each checked out submodule. @@@ -155,9 -162,9 +164,9 @@@ superproject, $sha1 is the commit as recorded in the superproject, and $toplevel is the absolute path to the top-level of the superproject. Any submodules defined in the superproject but not checked out are - ignored by this command. Unless given --quiet, foreach prints the name + ignored by this command. Unless given `--quiet`, foreach prints the name of each submodule before evaluating the command. - If --recursive is given, submodules are traversed recursively (i.e. + If `--recursive` is given, submodules are traversed recursively (i.e. the given shell command is evaluated in nested submodules as well). A non-zero return from the command in any submodule causes the processing to terminate. This can be overridden by adding '|| :' @@@ -169,14 -176,12 +178,14 @@@ commit for each submodule sync:: Synchronizes submodules' remote URL configuration setting - to the value specified in .gitmodules. This is useful when + to the value specified in .gitmodules. It will only affect those + submodules which already have an url entry in .git/config (that is the + case when they are initialized or freshly added). This is useful when submodule URLs change upstream and you need to update your local repositories accordingly. + "git submodule sync" synchronizes all submodules while -"git submodule sync -- A" synchronizes submodule "A" only. +"git submodule sync \-- A" synchronizes submodule "A" only. OPTIONS ------- @@@ -237,13 -242,18 +246,18 @@@ If the key `submodule.$name.update` is set to `rebase`, this option is implicit. + --init:: + This option is only valid for the update command. + Initialize all submodules for which "git submodule init" has not been + called so far before updating. + --reference :: This option is only valid for add and update commands. These commands sometimes need to clone a remote repository. In this case, this option will be passed to the linkgit:git-clone[1] command. + *NOTE*: Do *not* use this option unless you have read the note - for linkgit:git-clone[1]'s --reference and --shared options carefully. + for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully. --recursive:: This option is only valid for foreach, update and status commands.