Merge branch 'ms/doc-worktree-side-by-side' into seen

Document "git worktree add" and use of out-of-tree worktrees with
examples.

Comments?

* ms/doc-worktree-side-by-side:
  amend! doc: git-worktree: Add side by side branch checkout example
  doc: git-worktree: Add side by side branch checkout example
  amend! doc: git-worktree: Link to examples
  doc: git-worktree: Link to examples

Author: gitster

Documentation/git-worktree.adoc

@@ -79,6 +79,9 @@ with a matching name, treat as equivalent to:
 $ git worktree add --track -b <branch> <path> <remote>/<branch>
 ------------
 +
+For best results it is advised to specify <path> outside of the repository and
+existing worktrees - see <<EXAMPLES>>
++
 If the branch exists in multiple remotes and one of them is named by
 the `checkout.defaultRemote` configuration variable, we'll use that
 one for the purposes of disambiguation, even if the _<branch>_ isn't
@@ -502,6 +505,7 @@ locked "reason\nwhy is locked"
 ...
 ------------
 
+[[EXAMPLES]]
 EXAMPLES
 --------
 You are in the middle of a refactoring session and your boss comes in and
@@ -522,6 +526,17 @@ $ popd
 $ git worktree remove ../temp
 ------------
 
+Side by side branch checkouts for a repository using multiple worktrees;
+let's imagine we participate in a project "bunny".
+
+------------
+mkdir
+cd bunny
+git clone --bare [email protected]:some-org/bunny bunny.git
+git --git-dir=bunny.git worktree add some-branch
+git --git-dir=bunny.git worktree add another-branch
+------------
+
 CONFIGURATION
 -------------