git/Documentation/git-submodule.txt, branch v2.13.2

submodule init: initialize active submodules

2017-03-18T16:51:23Z

Teach `submodule init` to initialize submodules which have been configured to be active by setting 'submodule.active' with a pathspec. Now if no path arguments are given and 'submodule.active' is configured, `init` will initialize all submodules which have been configured to be active. If no path arguments are given and 'submodule.active' is not configured, then `init` will retain the old behavior of initializing all submodules. This allows users to record more complex patterns as it saves retyping them whenever you invoke update. Signed-off-by: Brandon Williams Signed-off-by: Junio C Hamano

submodule init: warn about falling back to a local path

2017-02-28T21:46:22Z

When a submodule is initialized, the config variable 'submodule..url' is set depending on the value of the same variable in the .gitmodules file. When the URL indicates to be relative, then the url is computed relative to its default remote. The default remote cannot be determined accurately in all cases, such that it falls back to 'origin'. The 'origin' remote may not exist, though. In that case we give up looking for a suitable remote and we'll just assume it to be a local relative path. This can be confusing to users as there is a lot of guessing involved, which is not obvious to the user. So in the corner case of assuming a local autoritative truth, warn the user to lessen the confusion. This behavior was introduced in 4d6893200 (submodule add: allow relative repository path even when no url is set, 2011-06-06), which shared the code with submodule-init and then ported to C in 3604242f080a (submodule: port init from shell to C, 2016-04-15). In case of submodule-add, this behavior makes sense in some use cases[1], however for submodule-init there does not seem to be an immediate obvious use case to fall back to a local submodule. However there might be, so warn instead of die here. While adding the warning, also clarify the behavior of relative URLs in the documentation. [1] e.g. http://stackoverflow.com/questions/8721984/git-ignore-files-for-public-repository-but-not-for-private "store a secret locally in a submodule, with no intention to publish it" Reported-by: Shawn Pearce Signed-off-by: Stefan Beller Signed-off-by: Junio C Hamano

Merge branch 'jk/doc-submodule-markup-fix'

2017-02-15T22:56:40Z

Doc markup fix. * jk/doc-submodule-markup-fix: docs/git-submodule: fix unbalanced quote

docs/git-submodule: fix unbalanced quote

2017-02-13T22:05:40Z

The documentation gives an example of the submodule foreach command that uses both backticks and single-quotes. We stick the whole thing inside "+" markers to make it monospace, but the inside punctuation still needs escaping. We handle the backticks with "{backtick}", and use backslash-escaping for the single-quotes. But we missed the escaping on the second quote. Fortunately, asciidoc renders this unbalanced quote as we want (showing the quote), but asciidoctor does not. We could fix it by adding the missing backslash. However, let's take a step back. Even when rendered correctly, it's hard to read a long command stuck into the middle of a paragraph, and the important punctuation is hard to notice. Let's instead bump it into its own single-line code block. That makes both the source and the rendered result more readable, and as a bonus we don't have to worry about quoting at all. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

submodule update documentation: don't repeat ourselves

2017-01-12T22:19:32Z

The documentation for the `git submodule update` command, repeats itself for each update option, "This is done when

submodule documentation: add options to the subcommand

2017-01-12T22:19:32Z

When reading up on a subcommand of `git submodule `, it is convenient to have its options nearby and not just at the top of the man page. Add the options to each subcommand. While at it, also document the `--checkout` option for `update`. Signed-off-by: Stefan Beller Signed-off-by: Junio C Hamano

submodule: add absorb-git-dir function

2016-12-12T23:15:07Z

When a submodule has its git dir inside the working dir, the submodule support for checkout that we plan to add in a later patch will fail. Add functionality to migrate the git directory to be absorbed into the superprojects git directory. The newly added code in this patch is structured such that other areas of Git can also make use of it. The code in the submodule--helper is a mere wrapper and option parser for the function `absorb_git_dir_into_superproject`, that takes care of embedding the submodules git directory into the superprojects git dir. That function makes use of the more abstract function for this use case `relocate_gitdir`, which can be used by e.g. the worktree code eventually to move around a git directory. Signed-off-by: Stefan Beller Signed-off-by: Junio C Hamano

submodules doc: update documentation for "." used for submodule branches

2016-10-19T21:58:53Z

4d7bc52b17 ("submodule update: allow '.' for branch value", 2016-08-03) adopted from Gerrit a feature to set "." as a special value of "submodule..branch" in .gitmodules file to indicate that the tracking branch in the submodule should be the same as the current branch in the superproject. Update the documentation to describe this. Signed-off-by: Brandon Williams Signed-off-by: Junio C Hamano

submodule update: learn `--[no-]recommend-shallow` option

2016-05-27T17:40:46Z

Sometimes the history of a submodule is not considered important by the projects upstream. To make it easier for downstream users, allow a boolean field 'submodule..shallow' in .gitmodules, which can be used to recommend whether upstream considers the history important. This field is honored in the initial clone by default, it can be ignored by giving the `--no-recommend-shallow` option. Signed-off-by: Stefan Beller Signed-off-by: Junio C Hamano

Merge branch 'sb/submodule-deinit-all'

2016-05-17T21:38:20Z

Correct faulty recommendation to use "git submodule deinit ." when de-initialising all submodules, which would result in a strange error message in a pathological corner case. * sb/submodule-deinit-all: submodule deinit: require '--all' instead of '.' for all submodules