Mercurial documentation

• Theory
• Initial setup
• Basic usage
• Easy pullup: pcidevs change
• Complicated pullup: firefox update
• Applying pullups, releng side
• Maintaining third-party software on a vendor branch

---

Theory

Think of Mercurial as having a local VCS server, and having commands to sync between your local server and the remote one.

Initial setup

hg clone https://anonhg.NetBSD.org/src
hg clone https://anonhg.NetBSD.org/xsrc
hg clone https://anonhg.NetBSD.org/pkgsrc

adjust your username:

hg config --edit
  username = Mercurial User <[email protected]>

Basic usage

Basic usage:

hg add new-file.c
hg remove removed-file.c
hg mv old-name.c new-name.c

Inspect the state of your tree

hg diff
hg status

hg commit # Mercurial will commit all changed files in the repository.

Interact with the remote server:

hg pull				# Update your local repository from the remote
hg update			# Update your working tree to the latest trunk

hg outgoing			# Inspect state about to be pushed
hg push				# Update the remote repository

Easy pullup: pcidevs change

It is still possible to email a mail-index link to pullup-8, but let's show the alternative way, of creating the patch to send out. We want to backport a pcidevs change to netbsd-8, let's first find the change:

hg update netbsd-8
cd sys/dev/pci
hg log pcidevs

changeset:   447923:cfc8bf1e08b0
branch:      trunk
user:        msaitoh <[email protected]>
date:        Mon Jan 28 03:37:27 2019 +0000
summary:     Add AMD Family 17h devices from OpenBSD.

Now to apply it:

hg graft 447923

grafting 447923:cfc8bf1e08b0 " Add AMD Family 17h devices from OpenBSD."
merging sys/dev/pci/pcidevs
merge: warning: conflicts during merge
merging sys/dev/pci/pcidevs failed!
abort: unresolved conflicts, can't continue
(use 'hg resolve' and 'hg graft --continue')

The conflicts are most likely RCSIDs. Let's resolve them. open the file and look for "^=======":

<<<<<<< /home/fly/src-hg/sys/dev/pci/pcidevs
$NetBSD: pcidevs,v 1.1289.2.12 2018/12/04 12:02:12 martin Exp $
=======
$NetBSD: pcidevs,v 1.1359 2019/01/26 18:30:48 msaitoh Exp $
>>>>>>> /tmp/pcidevs~other.KuZska

Edit it to only show the CVS branch RCSID:

$NetBSD: pcidevs,v 1.1289.2.12 2018/12/04 12:02:12 martin Exp $

Mark the file resolved:

hg resolve -m pcidevs # Mark conflict as resolved
        (no more unresolved files)
        continue: hg graft --continue
hg graft --continue

We're done. Let's create a patch to send to releng:

    hg export -r "outgoing()" -o pullup-pcidevs

inspect pullup-pcidevs, and send this to pullup-8:

To: [email protected]
Subject: pcidevs update

Hello releng, please pullup this change to pcidevs.

Thanks, Mercurial User.

And attach pullup-pcidevs.

Complicated pullup: firefox update

We want to backport an update to firefox to pkgsrc-2018Q4, which has firefox 64.0. First, locate the commits we want to backport:

hg update pkgsrc-2018Q4 # Change to the branch
cd pkgsrc/www/firefox
hg log .

changeset:   318928:08850549da8a
branch:      trunk
user:        ryoon <[email protected]>
date:        Fri Feb 01 16:47:59 2019 +0000
summary:     Bump PKGREVISION

changeset:   318799:ae2a80757ebc
branch:      trunk
user:        tnn <[email protected]>
date:        Tue Jan 29 22:33:57 2019 +0000
summary:     remove obsolete hacks.mk & reduce diffs between mozilla derivative packages

changeset:   318788:3b3b81d77487
branch:      trunk
user:        ryoon <[email protected]>
date:        Tue Jan 29 16:28:22 2019 +0000
summary:     Updatet to 65.0

changeset:   318321:e0a4a2cb523a
branch:      trunk
user:        jperkin <[email protected]>
date:        Wed Jan 23 15:45:48 2019 +0000
summary:     firefox: Remove -pie on SunOS.

changeset:   317595:55e70f55a5a6
branch:      trunk
user:        ryoon <[email protected]>
date:        Thu Jan 10 13:37:40 2019 +0000
summary:     Update to 64.0.2

changeset:   316976:e0780dfada82
branch:      trunk
user:        gutteridge <[email protected]>
date:        Sun Dec 23 01:11:26 2018 +0000
summary:     firefox: fix .mk file inclusion order issue

changeset:   316509:6024a48bce43
branch:      trunk
user:        prlw1 <[email protected]>
date:        Fri Dec 14 10:21:27 2018 +0000
summary:     Fix build with webrtc option.

changeset:   316413:c57c62ca7a2d
branch:      trunk
user:        ryoon <[email protected]>
date:        Wed Dec 12 14:08:50 2018 +0000
summary:     Update to 64.0

We need the changes after 316413 (not including) to update 64->65. Let's naively try to combine all of them:

hg graft --log 316509 316976 317595 318321 318788 318799 318928
	skipping ancestor revision 316509:6024a48bce43
	skipping ancestor revision 316976:e0780dfada82
	grafting 317595:55e70f55a5a6 "Update to 64.0.2"
	grafting 318321:e0a4a2cb523a "firefox: Remove -pie on SunOS."
	grafting 318788:3b3b81d77487 "Updatet to 65.0"
	grafting 318799:ae2a80757ebc "remove obsolete hacks.mk & reduce diffs between mozilla derivative packages"
	merging mail/thunderbird/Makefile
	merge: warning: conflicts during merge
	merging mail/thunderbird/Makefile failed!
	abort: unresolved conflicts, can't continue
	(use 'hg resolve' and 'hg graft --continue')

This doesn't work because the commit:

318799:ae2a80757ebc "remove obsolete hacks.mk & reduce diffs between mozilla derivative packages"

has changes to multiple packages, and we don't want to pullup mail/thunderbird at this time.

hg graft --abort
hg graft --log 316509 316976 317595 318321 318788
hg diff -r 318799 . > my-manual-patch				# Create a patch only for www/firefox
patch -p3 -R < my-manual-patch					# Patch only www/firefox
hg commit -m "Manually merge 318799 changes to www/firefox"
hg graft --log 318928
	grafting 318928:08850549da8a "Bump PKGREVISION"

Test to make sure the package still works.

Now, let's export this all as a changeset to email:

hg export -r "outgoing()" -o pullup-firefox

pullup-firefox is a file containing all your changes, compared to the remote repository. Inspect that changes in it make sense, and then send it:

To: [email protected]
Subject: Firefox update to 65.0
Please update firefox to 65.0, a security fix.
Attached you will find a patch doing this.

Attach pullup-firefox

Thanks,
Mercurial User.

Once that's done, we can delete all our local changes:

hg strip -r 'draft()'

Applying pullups, releng side

hg import pullup-firefox

Maintaining third-party software on a vendor branch

Theory: create a branch where the only files are the ones from the vendor, so our new changes are easy to identify.

changeset:   8643:fba216e78634
branch:      trunk
user:        mrg <[email protected]>
date:        Fri May 31 00:34:34 2013 +0000
summary:     initial import of libXau-1.0.8

Let's save our local changes:

cd xsrc/external/mit/libXau/dist
hg diff -r 8643 . > /tmp/libXau-local-changes

Assuming no libXau vendor branch exists, let's create a new one. This tree will contain just libXau at its upstream version. Let's get an empty tree, the zeroth commit:

hg update 0
hg branch libXau
mkdir -p external/mit/libXau/dist
cd external/mit/libXau/dist
tar xvzf ~/Downloads/libXau-1.0.9.tar.gz
        libXau-1.0.9/AuRead.c
        libXau-1.0.9/INSTALL
        libXau-1.0.9/Makefile.in

That unpacked in libXau-1.0.9, let's move that to dist:

mv libXau-1.0.9/* .; rm -r libXau-1.0.9/

Now, commit our import:

hg add .
hg commit

Import libXau 1.0.9

Alan Coopersmith (3):
      XauFileName: always go through buf allocation if buf is NULL
      Update configure.ac bug URL for gitlab migration
      libXau 1.0.9

Let's try to merge that to trunk:

hg update trunk
hg merge -r libXau

Some merges will fail:
merging external/mit/libXau/dist/test-driver failed!
11 files updated, 0 files merged, 0 files removed, 18 files unresolved
use 'hg resolve' to retry unresolved file merges or 'hg merge --abort' to abandon

We want libXau 1.0.9 in the end, so let's resolve all those conflicts using their version:

hg resolve -t internal:other --all

Now, let's re-apply our local changes:

patch -p5 < /tmp/libXau-local-changes

Test that this works, adjust our local changes as needed, and commit:

hg commit -m "Merge libXau 1.0.9"