| Message ID | 20200228103558.1684937-3-damien.olivier.robert+git@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | doc: --recurse-submodules | expand |
> Le 28 févr. 2020 à 05:35, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > > Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> > --- > Documentation/git-reset.txt | 6 ++++++ > Documentation/git-restore.txt | 9 +++++++++ > 2 files changed, 15 insertions(+) > > diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt > index 932080c55d..838c0f1101 100644 > --- a/Documentation/git-reset.txt > +++ b/Documentation/git-reset.txt > @@ -87,6 +87,12 @@ but carries forward unmerged index entries. > different between `<commit>` and `HEAD`. > If a file that is different between `<commit>` and `HEAD` has local > changes, reset is aborted. > + > +--[no-]recurse-submodules:: > + When the working tree is updated, using --recurse-submodules will > + also recursively reset the content of all active submodules > + according to the commit recorded in the superproject, also setting > + the submodules HEAD to be detached at that commit. > — From previous testing I had done, when the submodule is modified (either modified content, new commits or new commits, staged) and `git reset` is invoked (and so `git reset HEAD` is assumed), the submodule is only touched if `--hard` or `--merge` is given, i.e. not when `--soft`, `--mixed` (the default action) or `--keep` are given. So this is in line with this option just coming into play "When the working tree is updated", as you wrote. However I just noticed that according to the doc `--merge` should abort in that case (I think?), but it does not if `--recurse-submodules` is given. I don’t know if it’s a doc oversight or a real bug though... > > See "Reset, restore and revert" in linkgit:git[1] for the differences > diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt > index 5bf60d4943..b94b2559c7 100644 > --- a/Documentation/git-restore.txt > +++ b/Documentation/git-restore.txt > @@ -107,6 +107,15 @@ in linkgit:git-checkout[1] for details. > patterns and unconditionally restores any files in > `<pathspec>`. > > +--recurse-submodules:: > +--no-recurse-submodules:: > + Using `--recurse-submodules` will update the content of all > + restored submodules according to the commit recorded in the > + superproject. I’d phrase it more like so : If `<pathspec>` names a submodule and the restore location includes the working tree, the submodule will only be updated if this option is given, in which case it’s working tree will be restored to the commit recorded in the superproject at the tree-ish given as the restore source. This makes it clearer that `git restore -- submodule` does nothing, and one has to say `git restore --recurse-submodules -- submodule` for the submodule working tree to be updated. > Local modifications in a restored submodule are > + overwritten. If nothing (or `--no-recurse-submodules`) is used, the > + work trees of submodules will not be updated. Just like > + linkgit:git-submodule[1], this will detach `HEAD` of the submodule. > + In fact `git submodule` does not unconditionally detach the submodules HEAD (if `git submodule update` is invoked and a branch is checked out in the submodule that points to the same commit as the one recorded in the superproject, the HEAD is not detached and the branch stays checked out unless `--force` is given.) So I would instead link to `checkout`, which does unconditionally detach the submodules HEAD. > --overlay:: > --no-overlay:: > In overlay mode, the command never removes files when > -- > Patched on top of v2.25.1-377-g2d2118b814 (git version 2.25.1) >
From Philippe Blain, Sun 01 Mar 2020 at 23:45:02 (-0500) : > > From previous testing I had done, when the submodule is modified (either modified content, > new commits or new commits, staged) and `git reset` is invoked (and so `git reset HEAD` is assumed), > the submodule is only touched if `--hard` or `--merge` is given, > i.e. not when `--soft`, `--mixed` (the default action) or `--keep` are given. > So this is in line with this option just coming into play "When the working tree is updated", as you wrote. Yes essentially reset.c only update the value of submodule.recurse according to --recurse-submodules. Then it is 'unpack-trees.c' that handle recursive submodules. > However I just noticed that according to the doc `--merge` should abort in that case (I think?), but it does not if > `--recurse-submodules` is given. I don’t know if it’s a doc oversight or a real bug though... Good question... > > + work trees of submodules will not be updated. Just like > > + linkgit:git-submodule[1], this will detach `HEAD` of the submodule. > In fact `git submodule` does not unconditionally detach the submodules HEAD > (if `git submodule update` is invoked and a branch is checked out in the submodule that points > to the same commit as the one recorded in the superproject, the HEAD is not detached and the branch > stays checked out unless `--force` is given.) So I would instead link to `checkout`, > which does unconditionally detach the submodules HEAD. Ok. I copied the above line from git-switch[1]. Should I also update it? git-checkout[1] also says that git-submodule will detach HEAD by the way.
> Le 3 mars 2020 à 12:26, Damien Robert <damien.olivier.robert@gmail.com> a écrit : > >>> + work trees of submodules will not be updated. Just like >>> + linkgit:git-submodule[1], this will detach `HEAD` of the submodule. > >> In fact `git submodule` does not unconditionally detach the submodules HEAD >> (if `git submodule update` is invoked and a branch is checked out in the submodule that points >> to the same commit as the one recorded in the superproject, the HEAD is not detached and the branch >> stays checked out unless `--force` is given.) So I would instead link to `checkout`, >> which does unconditionally detach the submodules HEAD. > > Ok. I copied the above line from git-switch[1]. Should I also update it? > git-checkout[1] also says that git-submodule will detach HEAD by the way. I would say yes: git-switch(1) should be updated to refer to git-checkout(1) instead of git-submodule(1), and git-checkout(1) should drop the reference to git-submodule(1) and just say that it will detach the submodule HEAD. Maybe in a separate patch before this one ?
diff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt index 932080c55d..838c0f1101 100644 --- a/Documentation/git-reset.txt +++ b/Documentation/git-reset.txt @@ -87,6 +87,12 @@ but carries forward unmerged index entries. different between `<commit>` and `HEAD`. If a file that is different between `<commit>` and `HEAD` has local changes, reset is aborted. + +--[no-]recurse-submodules:: + When the working tree is updated, using --recurse-submodules will + also recursively reset the content of all active submodules + according to the commit recorded in the superproject, also setting + the submodules HEAD to be detached at that commit. -- See "Reset, restore and revert" in linkgit:git[1] for the differences diff --git a/Documentation/git-restore.txt b/Documentation/git-restore.txt index 5bf60d4943..b94b2559c7 100644 --- a/Documentation/git-restore.txt +++ b/Documentation/git-restore.txt @@ -107,6 +107,15 @@ in linkgit:git-checkout[1] for details. patterns and unconditionally restores any files in `<pathspec>`. +--recurse-submodules:: +--no-recurse-submodules:: + Using `--recurse-submodules` will update the content of all + restored submodules according to the commit recorded in the + superproject. Local modifications in a restored submodule are + overwritten. If nothing (or `--no-recurse-submodules`) is used, the + work trees of submodules will not be updated. Just like + linkgit:git-submodule[1], this will detach `HEAD` of the submodule. + --overlay:: --no-overlay:: In overlay mode, the command never removes files when
Signed-off-by: Damien Robert <damien.olivier.robert+git@gmail.com> --- Documentation/git-reset.txt | 6 ++++++ Documentation/git-restore.txt | 9 +++++++++ 2 files changed, 15 insertions(+)