readme: write intro and start writing examples
improve README skeleton
readme: skeleton for the new README
Intro elevator pitch neat example differences from subrepo Installation Quick start if you have no guests yet if the guests are already there if you have subrepos Usage about only using the tip of the current branch commands Getting help Contributing reporting issues about the code contributing fixes running the test suite 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, contrariwise, lets you define the subrepos, and gives you a bunch of separate commands to update or inspect them all at once.
Explain everything using hggrmapping + hgguestrepo; we haven't switched to hggrconf + hggrsnap yet, so mention that only in the project overview
Linux: Clone the repo Add guestrepo = .../.../ to your hgrc
Windows: Clone the repo Add guestrepo = C:...... to your hgrc
# .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"
Specify the files in .hggrmapping
and .hguestrepo
Run hg grupdate --local
Specify the guestrepos in .hggrmapping
Run hg grfreeze
to create .hgguestrepo
Go through it to adjust any hashes to branch names/tags/...
Run hg grconvert
hg add .hggrconf hggrsnap
hg rm .hgsub .hgsubstate
hg commit -m 'switch over from subrepo to guestrepo'
Up to and including 1.13
.hggrmapping
maps guest name to pull URI.hgguestrepo
maps guest name to folder + changeset id (hash, branch, tag, ...)In the development version
.hggrmapping
and .hgguestrepo
are still supported.hggrconf
maps guest name to pull URI, also to folder.hggrsnap
maps folder to changeset id.hggrconf
and .hggrsnap
will be
used.The available commands. You can type hg help <command>
to get more
detailed help.