8ed3d76d8d8b — sietse.brouwer default tip 8 years ago
readme: write intro and start writing examples
3b89da8d2acb — sietse.brouwer 8 years ago
improve README skeleton
612a79b36969 — sietse.brouwer 8 years ago
readme: skeleton for the new README



#Hg guestrepo

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 vs subrepo

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

#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 Run hg grupdate --local

#Quick start (the guests are already present)

Specify the guestrepos in .hggrmapping Run hg grfreeze to create .hgguestrepo Go through it to adjust any hashes to branch names/tags/...

#Quick start (you were using subrepo before)

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
  • If both old and new are present among the committed files, .hggrconf and .hggrsnap will be used.


The available commands. You can type hg help <command> to get more detailed help.

#Getting help