Mercurial documentation


Theory

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

Working tree commit update Local repository push pull Remote repository


A commit changes your local repository, "push" and "pull" are actions on all branches.
The working tree is the content of the actual directory in the filesystem.

Initial setup


    Get mercurial from pkgsrc/devel/mercurial or pkgin install mercurial.
    Obtain the source tree using:

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 <mynetbsdlogin@NetBSD.org>

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 <msaitoh@NetBSD.org>
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: pullup-8@NetBSD.org
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 <ryoon@pkgsrc.org>
date:        Fri Feb 01 16:47:59 2019 +0000
summary:     Bump PKGREVISION

changeset:   318799:ae2a80757ebc
branch:      trunk
user:        tnn <tnn@pkgsrc.org>
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 <ryoon@pkgsrc.org>
date:        Tue Jan 29 16:28:22 2019 +0000
summary:     Updatet to 65.0

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

changeset:   317595:55e70f55a5a6
branch:      trunk
user:        ryoon <ryoon@pkgsrc.org>
date:        Thu Jan 10 13:37:40 2019 +0000
summary:     Update to 64.0.2

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

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

changeset:   316413:c57c62ca7a2d
branch:      trunk
user:        ryoon <ryoon@pkgsrc.org>
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.

Let's start over, manually applying the patch in 318799:ae2a80757ebc only to www/firefox.
`hg diff .` will create a diff for the current directory only.

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: pullup-pkgsrc@NetBSD.org
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.

Let's import libXau 1.0.9, in xsrc external/mit/libXau/dist. First download the distribution tarball.
The main thing interesting us are our local diffs to re-apply, let's save them.
For this we must identify the libXau 1.0.8 commit/branch:

changeset:   8643:fba216e78634
branch:      trunk
user:        mrg <mrg@NetBSD.org>
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"