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

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

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

diff --cc Documentation/git-worktree.adoc
index f272f797837f454ea286cc9939929d6d42c8d6a8,692e81fe3a1f411144a1be635f92d3903e7aba50..0f82ec5439411d480e272198388a7d631e1b800a
--- 1/Documentation/git-worktree.adoc
--- 2/Documentation/git-worktree.adoc
+++ b/Documentation/git-worktree.adoc
@@@ -79,12 -79,15 +79,15 @@@ with a matching name, treat as equivale
  $ 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,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
 +one for the purposes of disambiguation, even if the _<branch>_ isn't
  unique across all remotes. Set it to
  e.g. `checkout.defaultRemote=origin` to always checkout remote
 -branches from there if `<branch>` is ambiguous but exists on the
 +branches from there if _<branch>_ is ambiguous but exists on the
  `origin` remote. See also `checkout.defaultRemote` in
  linkgit:git-config[1].
  +
@@@ -522,13 -522,16 +526,23 @@@ $ pop
  $ git worktree remove ../temp
  ------------
  
+ Side by side branch checkouts for a repository using multiple worktrees
+ 
+ ------------
+ mkdir some-repository
+ cd some-repository
+ git clone --bare gitforge@someforge.example.com:some-org/some-repository some-repository.git
+ git --git-dir=some-repository.git worktree add some-branch
+ git --git-dir=some-repository.git worktree add another-branch
+ ------------
+ 
 +CONFIGURATION
 +-------------
 +
 +include::includes/cmd-config-section-all.adoc[]
 +
 +include::config/worktree.adoc[]
 +
  BUGS
  ----
  Multiple checkout in general is still experimental, and the support