git-filter-repo.txt: add examples for --[to-]subdirectory-filter

I had lots of examples of these being horribly mis-used and being used in place
of each other; add some examples with some description of the repository layout
to try to avoid all that confusion.

Signed-off-by: Elijah Newren <newren@gmail.com>

Documentation/git-filter-repo.txt

@@ -593,6 +593,49 @@ baz/foo/bar/bleh.txt.  Note the special line prefixes of `glob:` and
 
 Finally, see also the `--filename-callback` from <<CALLBACKS>>.
 
+Directory based shortcuts
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Let's say you had a directory structure like the following:
+
+   module/
+      foo.c
+      bar.c
+   otherDir/
+      blah.config
+      stuff.txt
+   zebra.jpg
+
+If you wanted just the module/ directory and you wanted it to become the
+new root so that your new directory structure looked like
+
+      foo.c
+      bar.c
+
+then you could run:
+
+--------------------------------------------------
+git filter-repo --subdirectory-filter module/
+--------------------------------------------------
+
+If you wanted all the files from the original repo, but wanted to move
+everything under a subdirectory named my-module/, so that your new
+directory structure looked like
+
+   my-module/
+      module/
+         foo.c
+         bar.c
+      otherDir/
+         blah.config
+         stuff.txt
+      zebra.jpg
+
+then you would instead run run
+
+--------------------------------------------------
+git filter-repo --to-subdirectory-filter my-module/
+--------------------------------------------------
+
 Content based filtering
 ~~~~~~~~~~~~~~~~~~~~~~~