Add documentation for 'meson subprojects' command line

2 files changed, 53 insertions, 1 deletions

diff --git a/docs/markdown/Subprojects.md b/docs/markdown/Subprojects.md
index 2e3e2ead5..ed118522e 100644
--- a/docs/markdown/Subprojects.md
+++ b/docs/markdown/Subprojects.md
@@ -179,7 +179,7 @@ the following command-line options:
     This is useful (mostly for distros) when you want to only use the
     sources provided by a software release, and want to manually handle
     or provide missing dependencies.
-    
+
 * **--wrap-mode=nofallback**
 
     Meson will not use subproject fallbacks for any dependency
@@ -196,6 +196,51 @@ the following command-line options:
     want to specifically build against the library sources provided by
     your subprojects.
 
+## Download subprojects
+
+*Since 0.49.0*
+
+Meson will automatically download needed subprojects during configure, unless
+**--wrap-mode=nodownload** option is passed. It is sometimes preferable to
+download all subprojects in advance, so the meson configure can be performed
+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
+
+*Since 0.49.0*
+
+Once a subproject has been fetched, Meson will not update it automatically.
+For example if the wrap file tracks a git branch, it won't pull latest commits.
+
+To pull latest version of all your subprojects at once, just run the command:
+`meson subprojects update`.
+- If the wrap file comes from wrapdb, the latest version of the wrap file will
+  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
+
+*Since 0.49.0*
+
+The command-line `meson subprojects checkout <branch_name>` will checkout a
+branch, or create one with `-b` argument, in every git subprojects. This is
+useful when starting local changes across multiple subprojects. It is still your
+responsability to commit and push in each repository where you made local
+changes.
+
+To come back to the revision set in wrap file (i.e. master), just run
+`meson subprojects checkout` with no branch name.
+
 ## Why must all subprojects be inside a single directory?
 
 There are several reasons.
diff --git a/docs/markdown/snippets/subprojects_cmd.md b/docs/markdown/snippets/subprojects_cmd.md
new file mode 100644
index 000000000..20fef5cad
--- /dev/null
+++ b/docs/markdown/snippets/subprojects_cmd.md
@@ -0,0 +1,7 @@
+## Subprojects download, checkout, update command-line
+
+New command-line tool has been added to manage subprojects:
+
+- `meson subprojects download` to download all subprojects that have a wrap file.
+- `meson subprojects update` to update all subprojects to latest version.
+- `meson subprojects checkout` to checkout or create a branch in all git subprojects.