cmd: explain project/repo nesting in init ref. (#1661)

* cmd: review repro examples
per #1572 (comment)

* cmd: fic tyupo in get-url

* cmd: updates to repro
per #1572 (review)

* cmd: rewrite repro -P desc
rel #1572 (review)

* cmd: simplified and generalize repro targets desc and DVC file mention
per #1572 (comment)
and #1572 (comment)

* cmd: minor update for repro desc wording
per #1572 (comment)

* term: don't use "synchronize" in the context of checkout

* cmd: rewrite Downstream example and added info for sequential execution of stages

* Update content/docs/command-reference/repro.md

* Update content/docs/command-reference/repro.md

* Update content/docs/command-reference/repro.md

* cmd: Updated Downstream example

* Update content/docs/command-reference/repro.md

* repro: Updated Downstream example

* Update content/docs/command-reference/repro.md

* cmd: updated last para for the description of --downstream and improved formatting

* cmd: review language of init --subdir

* term: revuew usage of "granular", esp. around init --subdir

* repro.md: updated Downstream example

* cmd: improve init --subdir explanation

* cmd: add info about nested subrepos to init

* cmd: fix -P option desc.
per #1615 (review)

* cmd: improve explanation on how --subdir affects commands
per #1615 (review)

* cmd: simplify nested structures explanation in init
per #1615 (comment)

* guide: add note aboud `cp` not being a download in external deps
per #1643 (review)

* cmd: add note about what --cwd means to repro
per iterative/dvc#4292 (comment)

* guide: nvmd! removing that note in external deps
per 42b670f#r41087633

* Update content/docs/command-reference/repro.md

* Update content/docs/command-reference/repro.md

* Update content/docs/command-reference/repro.md

* Update content/docs/command-reference/repro.md

* Update content/docs/command-reference/repro.md

* cmd: more small updates to init

* Update content/docs/command-reference/repro.md

* Update content/docs/command-reference/repro.md

* Restyled by prettier

* cmd: rewrap metrics diff usage paragraph

* term: remove "just" from -j desc in 3 refs
per eda27fc

* cmd: add command examples to init --subdir use cases
per #1615

* cmd: explain nested repo and projects of all kinds outside of --subdir
per #1615 (review)

* cmd: remove bold names to nested and not-nested structure examples in init --subdir
per #1615 (review)

* cmd: standardize --jobs option in all refs
per #1615 (review)
et al.

* cmd: add speed note to --jobs desc in all refs.
per #1615 (review)

* cmd: change versioning command example in init
per #1615 (review)

* cd: change repo comments in init --subdir examples
for #1615 (review)

* cmd: improve note on DVC submodules a little
for #1615 (review)

* cmd: better explain why isolation is important in --subdir bullet
per #1615 (review)

* cmd: split last --subdir cases explicitly as 2 bullets
per #1615 (comment)

* cmd: remove most notes and code block examples about nesting projects/repos in init
per #1615 (review)

* cmd: add basic text about nesting to init

* cmd: revert nested block examples back into --subdir
per #1661 (review)

* cmd: remove new section about nesting to revert more

Co-authored-by: sarthakforwet <[email protected]>
Co-authored-by: Restyled.io <[email protected]>

content/docs/command-reference/init.md

@@ -72,8 +72,43 @@ With `--subdir`, the project root will be found before the Git root, making sure
 the scope of DVC commands run here is constrained to this project alone, even if
 there are more DVC-related files elsewhere in the repo.
 
-Similarly, DVC commands run outside this project root (if nested inside another
-DVC project, for example) will ignore this project's contents completely.
+If there are multiple `--subdir` projects, but not nested, e.g.:
+
+```dvc
+.           # git init
+├── .git
+├── project-A
+│   ├── .dvc    # dvc init --subdir
+│   ...
+├── project-B
+│   ├── .dvc    # dvc init --subdir
+│   ...
+```
+
+DVC considers A and B separate projects. Any DVC command run in `project-A` is
+not aware of `project-B`. However, commands that involve versioning (like
+`dvc diff`, among others) access the commit history from the Git root (`.`).
+
+> `.` is not a DVC project in this case, so most DVC commands can't be run
+> there.
+
+If there are nested `--subdir` projects e.g.:
+
+```dvc
+project-A
+├── .dvc        # git init && dvc init
+├── .git
+├── dvc.yaml
+├── ...
+├── project-B
+│   ├── .dvc        # dvc init --subdir
+│   ├── data-B.dvc
+│   ...
+```
+
+Nothing changes for the inner projects. And any DVC command run in the outer one
+actively ignores the nested project directories. For example, using `dvc pull`
+in `project-A` wouldn't download data for the `data-B.dvc` file.
 
 ### Initializing DVC without Git