Conary:Mercurial Version Control

From rPath Wiki

Mercurial Primer

Conary development uses the Mercurial revision control system for managing Conary source code revisions. Here's a primer on using Mercurial to access the Conary repository:

• Make sure that Mercurial is installed:

conary update mercurial=contrib.rpath.org@rpl:devel

• Create a ~/.hgrc file that has your contact information:

[ui]
username = John Doe <contactinfo>

where contactinfo can be your email address, home page, or OpenPGP key fingerprint. man hgrc for more information on other things you can put in your ~/.hgrc file.

• You may also wish to install hgk, the graphical repository browser for Mercurial repositories; install it with the following command:

conary update mercurial-hgk

• Check out a copy of the repository:

hg clone http://hg.rpath.com/conary/

This will create a subdirectory called conary under your current working directory. Note that this creates a copy of the entire repository (kept in the conary/.hg directory); it is not merely a checked-out working directory. It is not very big (about 12MB as this is written).

Having the whole repository makes repository operations practically instantaneous, and also allows repository operations, including commits, even when you are disconnected from the repository. Your clone is actually a peer of our repository; this is not really a client-server relationship. This is an important point to keep in mind; if you don't understand this, then the rest of the process will seem a bit convoluted.

• To update your checked-out copy of the repository:

hg pull

This does nothing to your working copy; it merely updates the repository with all the new changesets that have been added since you cloned the repository, or since the last time you pulled. Pull frequently to make your merges easier.

• To update your working directory:

hg update

Mercurial will tell you if you need to use hg update -m instead. (You are very unlikely to want to use hg update -C since that throws away your changes.)

• To commit your work to your local repository:

hg commit

The first line of your commit message must be the one-line summary of your change. After that line, please leave a blank line that separates the summary from any additional information. Please provide plenty of useful information, especially for substantial changes.

• To see what you have committed to your repository that was not in the upstream repository as of the last time you ran hg pull, run:

hg out -p

• To send your current changes to rPath:

hg bundle yourchanges.bundle

where yourchanges is a descriptive name for the changes you are bundling up. Then send a OpenPGP-signed email message containing the bundle to conary-list@lists.rpath.com (you need to be subscribed in order for your post to be approved, as an anti-spam measure).

Please provide a description of the changes, including the commit messages, separate from the bundle to make it easier to evaluate the changes. Alternatively, you can put your changes in an Internet-accessible repository, and send an OpenPGP-signed email message telling us which changesets you would like us to pull. Again, include all relevant description. (We are likely to fine-tune the best way to submit changes over time.)

• If you are doing development of two unrelated streams, do them in different repositories:

hg clone conary conary-feature1
hg clone conary conary-feature2

This will create two (hard-linked for efficient file storage) clones of your local repository in which you can do specific feature development. You can send patches or bundles from each of them separately. These clones of repositories are how branches are handled in Mercurial (like many new version control systems).

Be aware that the repository from which each of these clones will pull by default is your initial local repository from which they are cloned; to change that, you can edit the files conary-feature1/.hg/hgrc and conary-feature2/.hg/hgrc and change the default line to point to http://hg.rpath.com/conary.

• If you are doing significant work, talk to us on conary-list@lists.rpath.com or freenode #conary first to make sure that we agree about the general direction of the work.

Finally, before contributing code to the project, be sure to see the Copyright Assignment information.