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

Merge branch 'sb/submodule-doc'

2017-07-12T22:18:21Z

Doc update. * sb/submodule-doc: submodules: overhaul documentation

Merge branch 'vs/typofixes'

2017-06-30T20:45:25Z

Many typofixes. * vs/typofixes: Spelling fixes

Spelling fixes

2017-06-27T17:35:49Z

Signed-off-by: Ville Skyttä Signed-off-by: Junio C Hamano

submodules: overhaul documentation

2017-06-22T22:25:25Z

This patch aims to detangle (a) the usage of `git-submodule` from (b) the concept of submodules and (c) how the actual implementation looks like, such as where they are configured and (d) what the best practices are. To do so, move the conceptual parts of the 'git-submodule' man page to a new man page gitsubmodules(7). This new page is just like gitmodules(5), gitattributes(5), gitcredentials(7), gitnamespaces(7), gittutorial(7), which introduce a concept rather than explaining a specific command. Signed-off-by: Stefan Beller Signed-off-by: Junio C Hamano

Documentation/git-submodule: cleanup "add" section

2017-06-22T19:38:52Z

The "add" section for 'git-submodule' is redundant in its description and the short synopsis line. Fix it. Remove the redundant mentioning of the 'repository' argument being mandatory. The text is hard to read because of back-references, so remove those. Replace the word "humanish" by "canonical" as that conveys better what we do to guess the path. While at it, quote all occurrences of '.gitmodules' as that is an important file in the submodule context, also link to it on its first mention. Helped-by: Stefan Beller Signed-off-by: Kaartic Sivaraam Reviewed-by: Stefan Beller Signed-off-by: Junio C Hamano

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