wiki:WorkingConventions/Git

  1. Guidelines for using git with GHC
  2. Setup
    1. General Guidelines
    2. Author
    3. Line endings
    4. Push access
      1. Ignoring unrecorded changes in submodules
  3. Working with the tree
    1. Tricks
    2. Commit messages
    3. Contributing patches
    4. Applying patches from email
  4. Submodules
  5. Branches
    1. The stable branch
    2. Development branches

Guidelines for using git with GHC

GHC uses ​Git (version 1.7.3.4 or newer recommended) for revision control. This page describes various GHC-specific conventions for using Git, together with some suggestions and tips for using Git effectively.

Setup

This page is mostly concerned about using Git for contributing actively to GHC and extends upon the instructions provided in Building/GettingTheSources.

General Guidelines

  • Try to make small patches (i.e. work in consistent increments).
  • Separate changes that affect functionality from those that just affect code layout, indentation, whitespace, filenames etc. This means that when looking at patches later, we don't have to wade through loads of non-functional changes to get to the important parts of the patch.
  • If possible, commit often. This helps to avoid conflicts.
  • Discuss anything you think might be controversial before pushing it.

Author

Please make sure you have setup git to use the correct name and email for your commits. Use the same name and email on all machines you may push from. 

$ git config --global user.name "Firstname Lastname" # Sets the name of the user for all git instances on the system
$ git config --global user.email "[email protected]"

This will set your name and email globally. To set it for just the GHC repo, remove the --global flag. Also, the environment variables GIT_COMMITTER_NAME, GIT_COMMITTER_EMAIL, GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL will override git-config settings if they are defined.

Line endings

Files in GHC repos should use Unix conventions for line endings. If you are on Windows, ensure that git handles line-endings sanely by running: 

git config --global core.autocrlf false

To find out what files in your tree have windows (CRLF) line endings, use 

find . -name '*hs' | xargs file | grep CRLF

Do this before you commit them!

Push access

If (as a developer) you have been granted push privileges to git.haskell.org, you need to take into account that only the ssh:// URLs support authentication (and hence git pushing to).

The following Git URL rewrite rules (which need to be configured only once as they're persisted in the ${HOME}/.gitconfig file due to --global) take care of transparently redirecting git pushes to the ssh:// Git URL counterparts: 

git config --global url."ssh://[email protected]/".pushInsteadOf git://git.haskell.org/

This uses the ssh:// protocol (which has much higher latency due to the SSH handshake occurring for each connect) only for git push operations, and the very fast unauthenticated git:// protocol for everything else (if you originally cloned git://git.haskell.org/ghc.git)

Ignoring unrecorded changes in submodules

You may probably also want to set 

  $ git config --global diff.ignoreSubmodules dirty

to stop Git in the ghc repo from checking for unrecorded changes in the submodules.

Working with the tree

Tricks

See WorkingConventions/Git/Tricks.

Commit messages

Please try to follow the general convention for the ​Git commit message structure as many Git tools rely on this. Moreover, take into account that the commit message text is interpreted as WikiFormatting in Trac.

In particular, if your patch addresses or fixes a bug/ticket, then include the ticket number in the form "#NNNN" in the commit message, e.g. 

  withMVar family have a bug (fixes #767)

Git will then add a link to the commit from the ticket (as soon as the commit becomes reachable from the master HEAD), so that people watching the ticket can see that a fix has been committed, and in the future we can easily find the patch that addressed the ticket. When navigating the Git history on Trac, you will also be able to jump directly to the ticket from the commit.

Contributing patches

The best and easiest way to contribute patches is to upload them to Phabricator. Other developers can review and comment on your patch, our automated systems will build and test it, and we can easily commit it when it's ready.

Alternatively you can send a patch to the mailing list using git. Please write your patch and then rebase to the latest version of GHC HEAD before sending to us. You can use the following command to send patches via email: 

git send-email --to=[email protected] <hash-id> -1

where <hash-id> is the hash of the commit to send. If you'd prefer to create patch files and send them via email another way (or attach them to trac tickets) then you can use this command: 

git format-patch [-o <outputdir>] <revision range>

Where <revision range> specifies the commit that git should stop at when going from HEAD backwards, creating a patch for each commit in the range <revision range>..HEAD.

Applying patches from email

git am -3 <email>

Submodules

GHC uses many git repositories which are tracked as Git submodules. For more information, check the Submodules page.

Branches

The stable branch

See WorkingConventions/Releases.

Development branches

See ActiveBranches for a description of known development branches.

The live list of currently existing branches in the ghc repository can be browsed via ​http://git.haskell.org/ghc.git/heads.

New development branches names should be prefixed with wip/ (e.g. "wip/dependent-types"), as otherwise the current Git server-side configuration disallows branch deletion and ​non-fast-forward updates.

Last modified 6 months ago Last modified on Sep 2, 2014 9:43:42 AM