readme: make --gem5-worktree docs awaesomer

README.adoc

@@ -10911,52 +10911,42 @@ Therefore, you can't forget to checkout to the sources to that of the correspond
 
 ===== gem5 worktree
 
-In order to checkout multiple gem5 builds and run them simultaneously, you also need to use the `--gem5-worktree` flag:
+<<gem5-build-variants,`--gem5-build-id`>> goes a long way, but if you want to seamlessly switch between two gem5 tress without checking out multiple times, then `--gem5-worktree` is for you.
 
 ....
-# Build master.
+# Build gem5 at the revision in the gem5 submodule.
 ./build-gem5
 
-# Build another branch.
-git -C "$(./getvar linux_src_dir)" checkout some-branch
-./build-gem5 --gem5-worktree some-branch
+# Create a branch at the same revision as the gem5 submodule.
+./build-gem5 --gem5-worktree my-new-feature
+cd "$(./getvar --gem5-worktree my-new-feature)"
+vim create-bugs
+git add .
+git commit -m 'Created a bug'
+cd -
+./build-gem5 --gem5-worktree my-new-feature
 
-# Restore master.
-git -C "$(./getvar linux_src_dir)" checkout -
-
-# Run master.
+# Run the submodule.
 ./run --gem5 --run-id 0 &>/dev/null &
 
-# Run another branch using the worktree for the scripts,
-# without the need to check out anything.
-./run --gem5 --gem5-worktree some-branch --run-id 1 &>/dev/null &
+# Run the branch the need to check out anything.
+# With --gem5-worktree, we can do both runs at the same time!
+./run --gem5 --gem5-worktree my-new-feature --run-id 1 &>/dev/null &
 ....
 
-This automatically creates a link:https://git-scm.com/docs/git-worktree[Git worktree] of gem5 if one didn't exit yet. Therefore, if you want to edit the code used by `--gem5-worktree-id`, you must edit it on the worktree:
+`--gem5-worktree <worktree-id>` automatically creates:
 
-....
-cd data/gem5/some-branch
-vim create-bugs
-git add -a && git commit -m 'commit bugs'
-....
+* a link:https://git-scm.com/docs/git-worktree[Git worktree] of gem5 if one didn't exit yet for `<worktree-id>`
+* a separate build directory, exactly like `--gem5-build-id my-new-feature` would
 
 We promise that the scripts sill never touch that worktree again once it has been created: it is now up to you to manage the code manually.
 
-When `--gem5-worktree` is not given, the default source tree under `submodules/gem5` is used.
+`--gem5-worktree` is required if you want to do multiple simultaneous runs of different gem5 versions, because each gem5 build needs to use the matching Python scripts inside the source tree.
 
-The `--gem5-worktree <woktree-id>` command determines the location of the gem5 tree to be used for both:
-
-* the input C files of the build at build time
-* the Python scripts to be used at runtime
-
-The difference between `--gem5-build-id` and `--gem5-worktree` is that `--gem5-build-id` specifies the gem5 build output directory, while `--gem5-worktree` specifies the source input directory.
-
-`--gem5-worktree` also sets `--gem5-build-id` by default, so that different worktrees lead to different builds by default.
+The difference between `--gem5-build-id` and `--gem5-worktree` is that `--gem5-build-id` specifies only the gem5 build output directory, while `--gem5-worktree` specifies the source input directory.
 
 Each Git worktree needs a branch name, and we append the `wt/` prefix to the `--gem5-worktree` value, where `wt` stands for `WorkTree`. This is done to allow us to checkout to a test `some-branch` branch under `submodules/gem5` and still use `--gem5-worktree some-branch`, without conflict for the worktree branch, which can only be checked out once.
 
-`--gem5-worktree` is only required if you have multiple gem5 checkouts, e.g. it would not be required for multiple builds of the same tree, e.g. a <<gem5-debug-build>> and a non-debug one.
-
 ===== gem5 private source trees
 
 Suppose that you are working on a private fork of gem5, but you want to use this repository to develop it as well.
@@ -11001,6 +10991,8 @@ The `gem5.debug` executable has optimizations turned off unlike the default `gem
 
 The build outputs are automatically stored in a different directory from other build types such as `.opt` build, which prevents `.debug` files from overwriting `.opt` ones.
 
+Therefore, `--gem5-build-id` is not required.
+
 The price to pay for debuggability is high however: a Linux kernel boot was about 14 times slower than opt at 71e927e63bda6507d5a528f22c78d65099bdf36f between the commands:
 
 ....