@@ 7,7 7,7 @@ Intro
   differences from subrepo
 Installation
 Quick start
-  if you have no guests
+  if you have no guests yet
   if the guests are already there
   if you have subrepos
 Usage

          
@@ 23,12 23,51 @@ Changelog
 License
 
 
+Guestrepo is like Subrepo, but it doesn't hang if one of your subrepositories
+is unable to push or pull. Instead, you are allowed and required to manage your
+subrepositories manually, and it gives you the commands to do so efficiently.
+
+If you have subrepos whose upstreams you do not manage yourself, but to which
+you occasionally make your own commits, you will probably prefer the guestrepo
+extension over the built-in subrepo support.
+
+
+Example: you have two guest repos. Of one, you want to follow the default branch; the
+other, you have pinned at a specific tag.
+
+    hg grsummary
+
+    # print incoming changes
+    hg grin
+
+    searching for changes
+    changeset:   1:6b43d531511b
+    ...
+    summary:     1
+
+    searching for changes
+    comparing with /mnt/data/sietse/proj/tryhg/hgguestrepo/two
+    changeset:   1:535f86f61ed3
+    ...
+    summary:     1
+
+    # fetch incoming changes
+    hg grpull
+
+    hg grsummary
+
+    # update one subrepo; the other remains static
+    hg grupdate
+
+    hg grsummary
+
+When you have added sub
+`commit` commits in all subrepos, `update` will update all subrepos, and it is
+impossible to `push` without doing the same for all subrepos.
+
+
 ### guestrepo vs subrepo
 
-Subrepo wires a lot of subrepo automation into the ordinary hg commands:
-`commit` commits in all subrepos, `update` will update all subrepos, and
-it is impossible to `pull` and `push` without doing the same for all
-subrepos.
 
 Guestrepo, contrariwise, lets you define the subrepos, and gives you a
 bunch of separate commands to update or inspect them all at once.

          
@@ 51,6 90,23 @@ Add guestrepo = C:\...\... to your hgrc
 Quick start
 -----------
 
+    # .hggrmapping: friendly_name = ssh://url.to/upstream
+    # .hgguestrepo: path/to/guest/checkout = friendly_name revision_to_follow
+
+    mkdir guests
+
+    hg clone https://example.com/upstream_one guest_to_follow
+    echo 'follow = https://example.com/upstream_one' > .hgguestrepo
+    echo 'guests/guest_to_follow = follow develop' > .hgguestrepo
+
+    hg clone https://example.com/upstream_two static_guest
+    echo 'static = https://example.com/upstream_two' > .hgguestrepo
+    echo 'guests/static_guest = static a1b3c9' >> .hgguestrepo
+
+    hg add .hgguestrepo .hggrmapping
+
+    hg commit -m "Added guest repositories"
+
 ### Quick start (no guests yet)
 
 Specify the files in `.hggrmapping` and `.hguestrepo`