It's currently undocumented, and should be mentioned. I previously thought that git submodule status was displaying the behaviors of git submodule status --cached and was thus incorrectly documented, but that wasn't actually the case: turns out that git submodule status just doesn't work when not in the root directory. Manish Goregaokar (1): doc: Document 'git submodule status --cached' Documentation/git-submodule.txt | 3 +++ 1 file changed, 3 insertions(+) base-commit: 5fa0f5238b0cd46cfe7f6fa76c3f526ea98148d9 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-470%2FManishearth%2Fsubmodule-sha-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-470/Manishearth/submodule-sha-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/470 Range-diff vs v1: 1: 0eabb27ba0 ! 1: 3168924c3c Documentation: Correct man page for the SHAs reported by 'submodule status' @@ -1,11 +1,9 @@ Author: Manish Goregaokar <manishsmail@xxxxxxxxx> - Documentation: Correct man page for the SHAs reported by 'submodule status' + doc: Document 'git submodule status --cached' - 'git submodule status' reports the SHAs expected by the parent project, - not the SHAs that are actually checked out in the submodule. Checking - out a new SHA in a submodule will not change the output of 'git - submodule status' until you 'git add' the submodule. + 'git submodule status --cached' reports the SHAs expected by the parent project, + instead of the SHAs that are actually checked out in the submodule. Signed-off-by: Manish Goregaokar <manishsmail@xxxxxxxxx> @@ -13,13 +11,12 @@ --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ - URL in `.gitmodules`. - - status [--cached] [--recursive] [--] [<path>...]:: -- Show the status of the submodules. This will print the SHA-1 of the -- currently checked out commit for each submodule, along with the -+ Show the status of the submodules. This will print the SHA-1 -+ recorded in the superproject for each submodule, along with the - submodule path and the output of 'git describe' for the - SHA-1. Each SHA-1 will possibly be prefixed with `-` if the submodule is - not initialized, `+` if the currently checked out submodule commit + does not match the SHA-1 found in the index of the containing + repository and `U` if the submodule has merge conflicts. + + ++If `--cached` is specified, this command will instead print the SHA-1 ++recorded in the superproject for each submodule. +++ + If `--recursive` is specified, this command will recurse into nested + submodules, and show their status as well. + + -- gitgitgadget
