Read-write Git access

We have read/write access to the Git repository available for maintainers and significant developers.

Our web pages are managed via git.

Contents

  1. Authenticated access
  2. Setting up your local Git tree
  3. Write access policies
  4. Testing changes
  5. Checking in a change
  6. Creating and using branches
  7. Personal and Vendor branches
  8. Tips&Tricks around your account

Authenticated access

We provide authenticated access via the SSH protocol. This needs to be sponsored by an existing maintainer (someone with "write after approval" is not sufficient).

If you already have an account on sourceware.org / gcc.gnu.org, askadmin-requests@sourceware.org to add access to the GCC repository. Include the name of your sponsor and CC: them. Otherwise use this form, again specifying your sponsor.

We will then provision you and inform you by mail. At this point, check out a tree using the instructions below and add yourself to the MAINTAINERS file. Note: Your first and last names _must_be exactly the same between your account on gcc.gnu.org and the MAINTAINERS file. Place your name in the correct section following the conventions specified in the file (e.g. "Write After Approval" is "last name alphabetical order"). If you do not have an FSF copyright assignment on file, also add yourself to the DCO section in the file.

Then produce a diff to that file and circulate it to thegcc-patches list, whilst also checking in your change to test write access (approval from the mailing list is not needed in this one case). For all other changes, please be sure to follow the write access policies below.

Setting up your local Git tree

Check out the GCC sources by issuing the command:

git clone git+ssh://_username_@gcc.gnu.org/git/gcc.git gcc

where username is your user name at gcc.gnu.org.

It is also possible to convert an existing Git tree to use SSH by using git remote:

git remote set-url origin git+ssh://_username_@gcc.gnu.org/git/gcc.git

To avoid the nuisance of having to supply your passphrase for each operation, you may want to use ssh-agent(1) andssh-add(1).

To avoid messages about (lack of) X11 forwarding, put in your$HOME/.ssh/config an entry like:

Host gcc.gnu.org ForwardX11 no

Git needs to know your name and email address. If you have not already configured those in $HOME/.gitconfig, do:

git config --global user.name "_Your Name_" git config --global user.email "_Your Email Address_"

If you wish to use a different name or email address for GCC commits from that in $HOME/.gitconfig, you can configure that in an individual Git tree using similar invocations without --global.

Write access policies

The GCC project grants developers various levels of write access to and review authority over the GCC master sources. We have not put any technical enforcement in place, rather we rely on everyone to follow the appropriate policies.

Global reviewers.

A limited number of developers have global review permission and can approve other people's changes to any part of the compiler.

Localized write permission.

This is for people who have primary responsibility for ports, front ends, or other specific aspects of the compiler. These folks are allowed to make changes to areas they maintain and related documentation, web pages, and test cases (and target conditionals) without approval from anyone else, and approve other people's changes in those areas. They must get approval for changes elsewhere in the compiler.

Maintainers of a port maintain the relevant files ingcc/config, documentation, web pages, and test cases and aspects of these relevant to that port. Port maintainers do not have approval rights beyond this.

Localized review permission.

This is similar to localized write permission, except that reviewers required approval for their own changes.

Write after approval.

This is folks that make regular contributions, but do not fall into one of the previous categories. People with write after approval need to submit their patches to the list; once the patches have been approved by the appropriate maintainers the patches may be checked in. The steering committee or a well-established GCC maintainer (including reviewers) canapprove for write access any person with GNU copyright assignment or DCO certification in place and known to submit good patches.

The list of folks with write access to the repository can be found in the MAINTAINERS file in the GCC distribution.

When you have checked in a patch exactly as it has been approved, you do not need to tell that to people -- including the approver. People interested in when a particular patch is committed can check Git or the gcc-cvslist.

Free for all

The following changes can be made by everyone with write access:

Obvious fixes can be committed without prior approval. Just check in the fix and copy it to gcc-patches. A good test to determine whether a fix is obvious: will the person who objects to my work the most be able to find a fault with my fix? If the fix is later found to be faulty, it can always be rolled back. We don't want to get overly restrictive about checkin policies.

Similarly, no outside approval is needed to revert a patch that you checked in.

Importing files maintained outside the tree from their official versions.

Creating and using a branch for development, including outside the parts of the compiler one maintains, provided that changes on the branch have copyright assignments or DCOcertification. Merging such developments back to the mainline still needs approval in the usual way.

Testing changes

All changes must be tested according to the instructions for testing patchesbefore they are checked in. If you wrote the patch yourself, you should test it yourself, unless there is a reason why someone else must do it for you (for instance, if you are fixing a problem on a system you do not have access to). If you are checking in a patch for someone else, you only need to test it if they did not.

You must test exactly the change you intend to check in; it is not good enough to have tested an earlier variant. (Unless the only changes from the earlier variant are formatting and comment changes; if there are any changes to the code itself you should re-bootstrap.) It is a good idea to re-test patches which were submitted a long time ago before applying them, even if nothing appears to have changed.

When you post your change to gcc-patches, state the canonical name(s) of the platform(s) you used for testing.

These rules are designed to ensure that checked-in code does not contain bugs that prevent other people from continuing to get their work done. There will always be bugs, but these rules help to minimize the amount of time where the tree does not build at all. Repeated failure to adhere to these rules could result in the revocation of check-in privileges by the Steering Committee.

Checking in a change

The following is meant to provide a very quick overview of how to check in a change. It is not meant to be a replacement for the Git documentation but instead a supplement. The Git documentation is available both as part of the Git source distribution, as well ason the Git website.

In all the commands listed below, you can give an explicit list of filenames to the git command. We recommend you list files explicitly when performing checkins to avoid accidental checkins of local code.

We prefer that each checkin be of a complete, single logical change, which may affect multiple files. The log message for that checkin should be a summary line (often the subject line of the email) followed by a blank line, then any discussion of the patch, and then the complete ChangeLog entry for the change. This makes it easier to correlate changes across files, and minimizes the time the repository is inconsistent. If you have several unrelated changes, you should check them in separately.

  1. Sync your sources with the master repository via "git pull" before attempting a checkin; this will save you a little time if someone else has modified the source tree since the last time you synced your sources.
  2. Apply the patch to your local tree. On master and release branches, ChangeLog entries will be automatically added to the corresponding ChangeLog files based on the git commit message once a day. See the documentation ofChangeLog format.
  3. Make sure to rebuild any generated files affected by the patch and commit them with the files explicitly modified.
  4. If the patch adds any new files, such as testcases, use git add to make Git aware of them.
  5. We recommend using "git diff HEAD" after applying a patch to a local tree. Review the output to make sure that only the changes you want will be checked in. Also see if the copyright dates need to be updated.
  6. Use "git commit" to check in the patch; either name the files to commit explicitly on the command line, or use git commit -a to commit all modified files in the source tree (it is still necessary to use git add first for any new files). If committing a patch for someone else, use --author "_Author Name_<_Author@Email.Address_>" to credit the patch to its author. You can enter the log message via the "-m" argument to commit, or wait for the editor window to appear and enter the log message in the editor window. If you use git commit without -a, and without naming files explicitly, it will only commit files explicitly added with git add, and will ignore any changes to those files made after you called git add for them.
  7. After exiting the editor, Git will check in your changes locally. When your prompt returns the local checkin is finished, but you still need to push the changes to the shared repository; do git push. A message will be sent to the gcc-cvs mailing list indicating that a change was made. If git push gives an error because someone else has pushed their own changes to the same branch, do git pull --rebase before trying git pushagain. A typical error in this situation looks like:

    To git+ssh://gcc.gnu.org/git/gcc.git
    ! [rejected] master -> master (fetch first)
    error: failed to push some refs to 'git+ssh://gcc.gnu.org/git/gcc.git'
    hint: Updates were rejected because the remote contains work that you do
    hint: not have locally. This is usually caused by another repository pushing
    hint: to the same ref. You may want to first integrate the remote changes
    hint: (e.g., 'git pull ...') before pushing again.
    hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Creating and using branches

Git makes it very easy and cheap to create local branches for working on separate changes. To switch to a new local branch starting from your current HEAD, do

git checkout -b $BRANCH

If the branch is based on GCC master, you can set it up to rebase automatically with

git branch -u origin/master git config branch.$BRANCH.rebase true

To share a long-lived development branch publicly for collaboration with other developers, you can use git push as follows:

git push origin BRANCH:devel/BRANCH:devel/BRANCH:devel/BRANCH

Please document such branches at thelist of development branches.

Shared development branches should not rebase; instead, merge master in by hand occasionally as needed with a normal git merge master. But DO NOT then simply merge the branch back onto master; see below.

Merging and Rebasing

Every commit in the history of GCC master must follow the testing guidelines above; when a development branch is ready to move into master, do not do a simple git merge and push that onto master. Instead, invoke merge with --squash:

git merge --squash $BRANCH

This readies a single normal commit with the effect of the merge. If the merge can logically be divided into a series of commits that each pass testing, you can use git tools like git reset -p to break up the changes accordingly. It may be easier to cherry-pick some smaller changes onto master before doing the merge --squash.

For personal development branches that are already rebased on master you don't need to merge --squash squash, but still need to make sure the commits on the branch satisfy the above rules for commits.

Personal and vendor branches

The GCC git repository is used by many people and the branch and tag namespace would become very polluted if all branches lived at the top-level naming space. To help minimise the amount of data that needs to be fetched the git repository on gcc.gnu.org supports having personal and vendor spaces that developers use to share their work. These are not pulled by default, but simple configuration steps can give access to them.

Personal and vendor spaces are controlled by the individual user or vendor. Do not push changes to somebody else's space without their express permission. Rather than pushing to somebody else's branch, consider pushing to your own personal branch and having collaborators pull from there.

Scripts exist in the contrib directory to help manage these spaces.

contrib/gcc-git-customization.sh

This script will help set up your personal area. It will also define some aliases that might be useful when developing GCC. The script will first ask a number of questions:

If you have personal branches pushed to the gcc repository you can fetch updates from your personal space by runninggit fetch users/me (or whatever personal prefix you've chosen). You can also push an already existing branch using git push users/me me/branch. Beware that if you have more than one personal branch set up locally, simply typing git push users/me will potentially push all personal branches based on that remote.

Use --dry-run to check that what will be pushed is what you intend.

The script contrib/git-add-user-branch.shcan be used to create a new personal branch which can be pushed and pulled from the users/me remote. The script also defines a few useful aliases that can be used with the repository:

The final customization that the script makes is to add a diff rule so that running git diff on a machine description file (a file with the suffix .md) will annotate the diff hunk headers with the name of the pattern being modified (in much the same way as C function names are used).

contrib/git-fetch-vendor.sh

Vendor spaces are controlled by the named vendor. Do not push changes to that space without their express permission.

This script will set up a new 'remote' that can be used to access the area used by a named vendor. You need to run contrib/gcc-git-customization.sh before you can use this script.

The script requires one argument, the name of the vendor, and takes one option, --enable-push, to enable pushes to be made to the space. If invoked with no arguments the script will build a list of existing vendors from the server.

Once the script has been run, a new 'remote' will be configured with the name vendors/<vendor>. You can use this to fetch updates to that vendor's branches.

To check out an existing vendor branch, you can use:

git checkout -b / remotes/vendors//

This will create a tracking branch that can be updated with normal git operations, such as git pull.

If you have set up push access, then the branch can similarly be pushed to using:

git push vendors/ /

The script can be re-run with, or without --enable-push to enable, or disable push operations.

contrib/git-add-vendor-branch.sh

Before this script can be used contrib/git-fetch-vendor.sh should be run to set up the vendor-specific workspace. This applies even if the named vendor space does not yet exist on the server.

This script can be used to simplify the task of creating an initial vendor branch. The script takes two arguments, the name of the branch to create (including the vendor name) and the start point. For example, to create a test branch under the vendor megacorp run and starting from the most recent commit on master:

contrib/git-add-vendor-branch.sh / master

This will create the branch both locally and on the server, but will not check the branch out locally. You can do that afterwards withgit checkout or git worktree.

contrib/git-add-user-branch.sh

before this script can be used, your personal space access should be set up by running contrib/gcc-git-customization.sh.

The script takes two arguments, the name of the new branch to create and a ref to create it from. The personal prefix for the new branch is optional and will be automatically added if omitted. For example, if your personal prefix is the default (me), then running:

contrib/git-add-user-branch.sh topic master

will set up a branch called topic on the server and a local branch called me/topic that tracks it. The branch can then be pushed using:

git push users/me me/topic

Tips&Tricks around your account

Your gcc.gnu.org account also receives e-mail (and is what you use for Bugzilla). If you ever need to change the address e-mail to_username_@gcc.gnu.org is forwarded to, you can easily do so using

ssh username@gcc.gnu.org email mynewaddress@example.com

Similarly if you want to add a new SSH key to your account:

ssh username@gcc.gnu.org appendkey < KEYFILE

Or replace all your SSH keys:

ssh username@gcc.gnu.org replacekey < KEYFILE