git/Documentation/gitmodules.txt, branch v2.4.9

submodule: improve documentation of update subcommand

2015-03-02T22:59:55Z

The documentation of 'git submodule update' has several problems: 1) It mentions that value 'none' of submodule.$name.update can be overridden by --checkout, but other combinations of configuration values and command line options are not mentioned. 2) The documentation of submodule.$name.update is scattered across three places, which is confusing. 3) The documentation of submodule.$name.update in gitmodules.txt is incorrect, because the code always uses the value from .git/config and never from .gitmodules. 4) Documentation of --force was incomplete, because it is only effective in case of checkout method of update. Fix all these problems by documenting submodule.*.update in git-submodule.txt and make everybody else refer to it. Helped-by: Junio C Hamano Helped-by: Jens Lehmann Signed-off-by: Michal Sojka Signed-off-by: Junio C Hamano

status/commit: show staged submodules regardless of ignore config

2014-04-07T17:32:20Z

Currently setting submodule..ignore and/or diff.ignoreSubmodules to "all" suppresses all output of submodule changes for the diff family, status and commit. For status and commit this is really confusing, as it even when the user chooses to record a new commit for an ignored submodule by adding it manually this change won't show up under the to-be-committed changes. To add insult to injury, a later "git commit" will error out with "nothing to commit" when only ignored submodules are staged. Fix that by making wt_status always print staged submodule changes, no matter what ignore settings are configured. The only exception is when the user explicitly uses the "--ignore-submodules=all" command line option, in that case the submodule output is still suppressed. This also makes "git commit" work again when only modifications of ignored submodules are staged, as that command uses the "commitable" member of the wt_status struct to determine if staged changes are present. But this only happens when the commit command uses the wt_status* functions to produce status output for human consumption (when forking an editor or with --dry-run), in all other cases (e.g. when run in a script with '-m') another code path is taken which uses index_differs_from() to determine if any changes are staged which still ignores submodules according to their configuration. This will be fixed in a follow-up commit. Change t7508 to reflect this new behavior and add three new tests to show that a single staged submodule configured to be ignored will be committed when the status output is generated and won't be if not. Also update the documentation of the ignore config options accordingly. Signed-off-by: Jens Lehmann Signed-off-by: Junio C Hamano

Documentation/gitmodules: Only 'update' and 'url' are required

2014-01-06T17:08:18Z

Descriptions for all the settings fell under the initial "Each submodule section also contains the following required keys:". The example shows sections with just 'path' and 'url' entries, which are indeed required, but we should still make the required/optional distinction explicit to clarify that the rest of them are optional. Signed-off-by: W. Trevor King Reviewed-by: Heiko Voigt Signed-off-by: Junio C Hamano

Improve documentation concerning the status.submodulesummary setting

2013-09-11T19:20:41Z

'git status' and 'git commit' can be told to also show the output of "git submodule summary" by setting the "status.submodulesummary" config option. But status and commit also honor the "diff.ignoreSubmodules" and the "submodule..ignore" settings, which then disable the summary partly or completely. This - and the fact that the last two settings do not affect the "git submodule" commands at all - is not well documented. Extend the documentation in those places where "status.submodulesummary", "diff.ignoreSubmodules" and "submodule..ignore" are described to better explain these dependencies. Thanks-to: Matthieu Moy Signed-off-by: Jens Lehmann Signed-off-by: Junio C Hamano

Documentation: the name of the system is 'Git', not 'git'

2013-02-01T21:53:33Z

Signed-off-by: Thomas Ackermann Signed-off-by: Junio C Hamano

submodule update: add --remote for submodule's upstream changes

2012-12-19T17:40:01Z

The current `update` command incorporates the superproject's gitlinked SHA-1 ($sha1) into the submodule HEAD ($subsha1). Depending on the options you use, it may checkout $sha1, rebase the $subsha1 onto $sha1, or merge $sha1 into $subsha1. This helps you keep up with changes in the upstream superproject. However, it's also useful to stay up to date with changes in the upstream subproject. Previous workflows for incorporating such changes include the ungainly: $ git submodule foreach 'git checkout $(git config --file $toplevel/.gitmodules submodule.$name.branch) && git pull' With this patch, all of the useful functionality for incorporating superproject changes can be reused to incorporate upstream subproject updates. When you specify --remote, the target $sha1 is replaced with a $sha1 of the submodule's origin/master tracking branch. If you want to merge a different tracking branch, you can configure the `submodule..branch` option in `.gitmodules`. You can override the `.gitmodules` configuration setting for a particular superproject by configuring the option in that superproject's default configuration (using the usual configuration hierarchy, e.g. `.git/config`, `~/.gitconfig`, etc.). Previous use of submodule..branch ======================================= Because we're adding a new configuration option, it's a good idea to check if anyone else is already using the option. The foreach-pull example above was described by Ævar in commit f030c96d8643fa0a1a9b2bd9c2f36a77721fb61f Author: Ævar Arnfjörð Bjarmason Date: Fri May 21 16:10:10 2010 +0000 git-submodule foreach: Add $toplevel variable Gerrit uses the same interpretation for the setting, but because Gerrit has direct access to the subproject repositories, it updates the superproject repositories automatically when a subproject changes. Gerrit also accepts the special value '.', which it expands into the superproject's branch name. Although the --remote functionality is using `submodule..branch` slightly differently, the effect is the same. The foreach-pull example uses the option to record the name of the local branch to checkout before pulls. The tracking branch to be pulled is recorded in `.git/modules//config`, which was initialized by the module clone during `submodule add` or `submodule init`. Because the branch name stored in `submodule..branch` was likely the same as the branch name used during the initial `submodule add`, the same branch will be pulled in each workflow. Implementation details ====================== In order to ensure a current tracking branch state, `update --remote` fetches the submodule's remote repository before calculating the SHA-1. However, I didn't change the logic guarding the existing fetch: if test -z "$nofetch" then # Run fetch only if $sha1 isn't present or it # is not reachable from a ref. (clear_local_git_env; cd "$path" && ( (rev=$(git rev-list -n 1 $sha1 --not --all 2>/dev/null) && test -z "$rev") || git-fetch)) || die "$(eval_gettext "Unable to fetch in submodule path '\$path'")" fi There will not be a double-fetch, because the new $sha1 determined after the `--remote` triggered fetch should always exist in the repository. If it doesn't, it's because some racy process removed it from the submodule's repository and we *should* be re-fetching. Signed-off-by: W. Trevor King Signed-off-by: Junio C Hamano

Teach "git submodule add" the --name option

2012-09-30T04:49:11Z

"git submodule add" initializes the name of a submodule to its path. This was ok as long as the .git directory lived inside the submodule's work tree, but since 1.7.8 it is stored in the .git/modules/ directory of the superproject, making the submodule name survive the removal of the submodule's work tree. This leads to problems when the user tries to add a different submodule at the same path - and thus the same name - later, as that will happily try to restore the submodule from the old repository instead of the one the user specified and will lead to a checkout of the wrong repository. Add the new "--name" option to let the user provide a name for the submodule. This enables the user to solve this conflict without having to remove .git/modules/ by hand (which is no viable solution as it makes it impossible to checkout a commit that records the old submodule and populate it, as that will still check out the new submodule for the same reason). To achieve that the submodule's name is added to the parameter list of the module_clone() helper function. This makes it possible to remove the call of module_name() there because both callers of module_clone() already know the name and can provide it as argument number two. Reported-by: Jonathan Johnson Signed-off-by: Jens Lehmann Signed-off-by: Junio C Hamano

document submdule.$name.update=none option for gitmodules

2012-05-11T15:39:33Z

This option was not yet described in the gitmodules documentation. We only described it in the 'git submodule' command documentation but gitmodules is the more natural place to look. A short reference in the 'git submodule' documentation should be sufficient since the details can now be found in the documentation to gitmodules. Signed-off-by: Heiko Voigt Signed-off-by: Junio C Hamano

correct spelling: an URL -> a URL

2012-03-28T15:47:23Z

Signed-off-by: Jim Meyering Signed-off-by: Junio C Hamano

Merge branch 'jl/submodule-fetch-on-demand'

2011-04-04T22:02:01Z

* jl/submodule-fetch-on-demand: fetch/pull: Describe --recurse-submodule restrictions in the BUGS section submodule update: Don't fetch when the submodule commit is already present fetch/pull: Don't recurse into a submodule when commits are already present Submodules: Add 'on-demand' value for the 'fetchRecurseSubmodule' option config: teach the fetch.recurseSubmodules option the 'on-demand' value fetch/pull: Add the 'on-demand' value to the --recurse-submodules option fetch/pull: recurse into submodules when necessary Conflicts: builtin/fetch.c submodule.c