init: add subdir description

public/static/docs/command-reference/init.md

@@ -3,12 +3,12 @@
 This command initializes a <abbr>DVC project</abbr> on a directory.
 
 Note that by default the current working directory is expected to contain a Git
-repository, unless the `--no-scm` option is used.
+repository, unless the `--no-scm` or `--subdir` options are used.
 
 ## Synopsis
 
 ```usage
-usage: dvc init [-h] [-q | -v] [--no-scm] [-f]
+usage: dvc init [-h] [-q | -v] [--no-scm] [-f] [--subdir]
 ```
 
 ## Description
@@ -28,7 +28,12 @@ local cache and you cannot `git push` it.
 ## Options
 
 - `--no-scm` - skip Git specific initialization, `.dvc/.gitignore` will not be
-  written.
+  written. This option should not be combined with `--subdir` (below).
+
+- `--subdir` - allows initializing a <abbr>DVC repository</abbr> inside a
+  directory of a Git repo. DVC in this _subdir_ DVC repo will search for Git in
+  parent directories. This option should not be combined with `--no-scm`
+  (above).
 
 - `-f`, `--force` - remove `.dvc/` if it exists before initialization. Will
   remove any existing local cache. Useful when a previous `dvc init` has been
@@ -43,7 +48,9 @@ local cache and you cannot `git push` it.
 
 ## Examples
 
-Create a new <abbr>DVC repository</abbr> (requires Git):
+## Example: Create a new DVC repository
+
+Requires Git.
 
 ```dvc
 $ mkdir example && cd example
@@ -67,3 +74,31 @@ $ cat .dvc/.gitignore
 ...
 /cache
 ```
+
+## Example: Create a subdirectory DVC repository
+
+Let's create a parent Git repository, and then a <abbr>DVC project</abbr> inside
+a subdirectory.
+
+```dvc
+$ mkdir repo && cd repo
+
+$ git init
+$ mkdir subdir && cd subdir
+
+$ dvc init --subdir
+```
+
+The Git repo is in the `repo/` directory, while the _subdir_ DVC repository
+lives in `repo/subdir`.
+
+```dvc
+$ tree repo -a
+repo
+├── .git
+.
+.
+.
+└── subdir
+    └── .dvc
+```