Version 3 (modified by simonmar, 10 years ago) (diff)

move some stuff from WorkingConventions

Guidelines for using darcs with GHC

GHC uses darcs for revision control. This page describes various GHC-specific conventions for using darcs, together with some suggestions and tips for using darcs effectively.

Patch naming

We have a simple naming convention for certain kinds of patches:

  • If your patch fixes breakage in the build, then begin the patch name with "FIX BUILD". e.g.
      FIX BUILD Use the right find on Windows systems; fixes bindist creation
    The point here is that if someone pulls GHC from darcs and experiences a build failure, they can try darcs pull -a -p "FIX BUILD" in order to grab patches that fix it, without grabbing anything else that might introduce further breakage.
  • If your patch fixes a bug, then begin the patch name with "FIX #NNNN", where NNNN is the ticket number. e.g.
      FIX #767 (withMVar family have a bug)


Right now, we avoid having any conflicts in the GHC HEAD repository, because darcs currently doesn't handle conflicts well. Don't push and conflicts, even resolved ones, to the GHC HEAD. Instead amend-record or re-record your patches to fix the conflicts before pushing.

Conflicts on branches are less of a problem, because branches usually have a limited life-span. As long as the branch is not intended to be merged with the HEAD in the future (e.g. the stable branches), then small conflicts are ok.

We're aware that this policy creates problems for development branches of GHC, and this is truly unfortunate. We're hopeful that darcs' conflict handling will improve in the future and we can get the full power of darcs for separate development.

Committing changes

If you have permission to push patches directly to the repository (pretty easy to get, just demonstrate your competence by sending us a patch or two first), then you can use darcs push:

  $ darcs push <account>

(change ghc to the name of the repository if you're pushing changes from one of the sub-repositories, like testsuite, or a package such as base. Note: darcs push requires that SSH is working and can log in to your account on

Do not forget to darcs record your changes first!

Pushing a whole tree

A GHC tree consists of several repositories (see Building/GettingTheSources). Sometimes you want to push from them all at the same time, for example after running a validate (see TestingPatches).

It's good practice to have a completely clean set of repositories locally, i.e. a locally cached copy of the main repositories on This is useful for creating new trees quickly, or comparing your trees to the HEAD. To see which patches you have in a GHC tree relative to a clean repository, you can use the push-all script in the root of the GHC repository:

  $ ./push-all --checked-out ~/ghc-HEAD --dry-run

where ~/ghc-HEAD is my vanilla HEAD, with all the sub-repositories checked out using darcs-all. This command tells me all the patches in the local repository tree relative to ~/ghc-HEAD.

To actually push to the HEAD, you can do this:

  $ ./push-all

it'll use SSH for the push, but continue to use HTTP for pulling, which is what you want (HTTP is much faster than SSH for darcs operations, but for pushing we can only use SSH).