"W. Trevor King" <wk...@tremily.us> writes: > The old documentation did not distinguish between cloning and > non-cloning updates and lacked clarity on which operations would lead > to detached HEADs, and which would not. The new documentation > addresses these issues while updating the docs to reflect the changes > introduced by this branch's explicit local branch creation in > module_clone. > > I also add '--checkout' to the usage summary and group the update-mode > options into a single set. > > Signed-off-by: W. Trevor King <wk...@tremily.us> > --- > Documentation/git-submodule.txt | 36 +++++++++++++++++++++++++++--------- > Documentation/gitmodules.txt | 4 ++++ > 2 files changed, 31 insertions(+), 9 deletions(-) > > diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt > index bfef8a0..02500b4 100644 > --- a/Documentation/git-submodule.txt > +++ b/Documentation/git-submodule.txt > @@ -15,8 +15,8 @@ SYNOPSIS > 'git submodule' [--quiet] init [--] [<path>...] > 'git submodule' [--quiet] deinit [-f|--force] [--] <path>... > 'git submodule' [--quiet] update [--init] [--remote] [-N|--no-fetch] > - [-f|--force] [--rebase] [--reference <repository>] [--depth > <depth>] > - [--merge] [--recursive] [--] [<path>...] > + [-f|--force] [--rebase|--merge|--checkout] [--reference > <repository>] > + [--depth <depth>] [--recursive] [--] [<path>...] > 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) > <n>] > [commit] [--] [<path>...] > 'git submodule' [--quiet] foreach [--recursive] <command> > @@ -155,13 +155,31 @@ it contains local modifications. > > 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 > - `rebase`, `merge` or `none`. `none` can be overridden by specifying > - `--checkout`. Setting the key `submodule.$name.update` to `!command` > - will cause `command` to be run. `command` can be any arbitrary shell > - command that takes a single argument, namely the sha1 to update to. > + checkout the commit specified in the index of the containing > + repository. The update mode defaults to 'checkout', but be > + configured with the 'submodule.<name>.update' setting or the > + '--rebase', '--merge', or 'checkout' options.
Not '--checkout'? Other than that, the updated text above is far easier to understand. Good job. > ++ > +For updates that clone missing submodules, checkout-mode updates will > +create submodules with detached HEADs; all other modes will create > +submodules with a local branch named after 'submodule.<path>.branch'. > ++ > +For updates that do not clone missing submodules, the submodule's HEAD That is, updates that update submodules that are already checked out? > +is only touched when the remote reference does not match the > +submodule's HEAD (for none-mode updates, the submodule is never > +touched). The remote reference is usually the gitlinked commit from > +the superproject's tree, but with '--remote' it is the upstream > +subproject's 'submodule.<name>.branch'. This remote reference is > +integrated with the submodule's HEAD using the specified update mode. I think copying some motivation from the log message of 06b1abb5 (submodule update: add --remote for submodule's upstream changes, 2012-12-19) would help the readers here. A naïve expectation from a casual reader of the above would be "The superproject's tree ought to point at the same commit as the tip of the branch used in the submodule (modulo mirroring delays and somesuch), if the repository of the superproject and submodules are maintained properly", which would lead to "when would any sane person need to use --remote in the first place???". If I am reading 06b1abb5 correctly, the primary motivation behind "--remote" seems to be that it is exactly to help the person who wants to update superproject to satisify the "... are maintained properly" part by fetching the latest in each of the submodules in his superproject in preparation to 'git add .' them. I still do not think "--remote" was a better way than the "foreach", but that is a separate topic. If the person who works in the superproject does not control the progress of, and/or does not care what development is happening in, the submodules, he can push the superproject tree out without even bothering to update the commits in the submodules bound to his superproject tree, and the consumers of such a superproject could catch up with the advancement of submodule by using --remote individually to bring themselves up to date. But I do not think that is what you envisioned as the best recommended practice when you wrote 06b1abb5. > +For checkout-mode updates, that will result in a detached HEAD. For > +rebase- and merge-mode updates, the commit referenced by the > +submodule's HEAD may change, but the symbolic reference will remain > +unchanged (i.e. checked-out branches will still be checked-out > +branches, and detached HEADs will still be detached HEADs). If none > +of the builtin modes fit your needs, set 'submodule.<name>.update' to > +'!command' to configure a custom integration command. 'command' can > +be any arbitrary shell command that takes a single argument, namely > +the sha1 to update to. > + > If the submodule is not yet initialized, and you just want to use the > setting as stored in .gitmodules, you can automatically initialize the > diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt > index f7be93f..36e5447 100644 > --- a/Documentation/gitmodules.txt > +++ b/Documentation/gitmodules.txt > @@ -53,6 +53,10 @@ submodule.<name>.branch:: > A remote branch name for tracking updates in the upstream submodule. > If the option is not specified, it defaults to 'master'. See the > `--remote` documentation in linkgit:git-submodule[1] for details. > ++ > +This branch name is also used for the local branch created by > +non-checkout cloning updates. See the 'update' documentation in > +linkgit:git-submodule[1] for details. > > submodule.<name>.fetchRecurseSubmodules:: > This option can be used to control recursive fetching of this Other than the above minor nits, the updated text was very readable. Thanks. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
