doc: Update new `meson subprojects` behaviors

2 files changed, 63 insertions, 12 deletions

diff --git a/docs/markdown/Subprojects.md b/docs/markdown/Subprojects.md
index 02a83e6..57f5176 100644
--- a/docs/markdown/Subprojects.md
+++ b/docs/markdown/Subprojects.md
@@ -258,7 +258,22 @@ the following command-line options:
     `glib-2.0` must also be forced to fallback, in this case with
     `--force-fallback-for=glib,gsteamer`.
 
-## Download subprojects
+## `meson subprojects` command
+
+*Since 0.49.0*
+
+`meson subprojects` has various subcommands to manage all subprojects. If the
+subcommand fails on any subproject the execution continues with other subprojects.
+All subcommands accepts `--sourcedir` argument pointing to the root source dir
+of the main project.
+
+*Since 0.56.0* all subcommands accepts `--type <file,git,hg,svn>` argument to
+run the subcommands only on subprojects of the given type.
+
+*Since 0.56.0* If the subcommand fails on any subproject an error code is returned
+at the end instead of retuning success.
+
+### Download subprojects
 
 *Since 0.49.0*
 
@@ -269,7 +284,7 @@ offline. The command-line `meson subprojects download` can be used for that, it
 will download all missing subprojects, but will not update already fetched
 subprojects.
 
-## Update subprojects
+### Update subprojects
 
 *Since 0.49.0*
 
@@ -282,15 +297,22 @@ To pull latest version of all your subprojects at once, just run the command:
   be pulled and used next time meson reconfigure the project. This can be
   triggered using `meson --reconfigure`. Previous source tree is not deleted, to
   prevent from any loss of local changes.
-- If the wrap file points to a git commit or tag, a checkout of that commit is
-  performed.
-- If the wrap file points to a git branch, and the current branch has the same
-  name, a `git pull` is performed.
-- If the wrap file points to a git branch, and the current branch is different,
-  it is skipped. Unless `--rebase` option is passed in which case
-  `git pull --rebase` is performed.
-
-## Start a topic branch across all git subprojects
+- If subproject is currently in detached mode, a checkout of the revision from
+  wrap file is performed. *Since 0.56.0* a rebase is also performed in case the
+  revision already existed locally by was outdated. If `--reset` is specified,
+  a hard reset is performed instead of rebase.
+- If subproject is currently at the same branch as specified by the wrap file,
+  a rebase on `origin` commit is performed. *Since 0.56.0* If `--reset` is
+  specified, a hard reset is performed instead of rebase.
+- If subproject is currently in a different branch as specified by the wrap file,
+  it is skipped unless `--rebase` option is passed in which case a rebase on
+  `origin` commit is performed. *Since 0.56.0* the `--rebase` argument is
+  deprecated and has no effect. Instead, a checkout of the revision from wrap file
+  file is performed and a rebase is also performed in case the revision already
+  existed locally by was outdated. If `--reset` is specified, a hard reset is
+  performed instead of rebase.
+
+### Start a topic branch across all git subprojects
 
 *Since 0.49.0*
 
@@ -303,7 +325,9 @@ changes.
 To come back to the revision set in wrap file (i.e. master), just run
 `meson subprojects checkout` with no branch name.
 
-## Execute a command on all subprojects
+*Since 0.56.0* any pending changes are now stashed before checkout a new branch.
+
+### Execute a command on all subprojects
 
 *Since 0.51.0*
 
diff --git a/docs/markdown/snippets/subprojects_update.md b/docs/markdown/snippets/subprojects_update.md
new file mode 100644
index 0000000..598f70d
--- /dev/null
+++ b/docs/markdown/snippets/subprojects_update.md
@@ -0,0 +1,27 @@
+## `meson subprojects` command
+
+A new `--type` argument has been added to all subcommands to run the command only
+on wraps with the specified type. For example this command will only print `Hello`
+for each git subproject: `meson subprojects foreach --type git echo "Hello"`.
+
+Subprojects with no wrap file are now taken into account as well. This happens
+for example for subprojects configured as git submodule, or downloaded manually
+by the user and placed into the `subprojects/` directory.
+
+The `checkout` subcommand now always stash any pending changes before switching
+branch. Note that `update` subcommand was already stashing changes before updating
+the branch.
+
+If the command fails on any subproject the execution continues with other
+subprojects, but at the end an error code is now returned.
+
+The `update` subcommand has been reworked:
+- The `--rebase` behaviour is now the default for consistency: it was
+  already rebasing when current branch and revision are the same, it is
+  less confusing to rebase when they are different too.
+- Add `--reset` mode that checkout the new branch and hard reset that
+  branch to remote commit. This new mode guarantees that every
+  subproject are exactly at the wrap's revision.
+- Local changes are always stashed first to avoid any data loss. In the
+  worst case scenario the user can always check reflog and stash list to
+  rollback.